From 8c148d0449552ca8262b7641b24cc85751370cfe Mon Sep 17 00:00:00 2001
From: "Leona B. Campbell" <3880403+runleonarun@users.noreply.github.com>
Date: Wed, 2 Oct 2024 16:05:32 -0700
Subject: [PATCH] Adding caveat to the false positives (#6207)

Closes https://github.com/dbt-labs/docs.getdbt.com/issues/6197

## What are you changing in this pull request and why?

Adjusting false positives section to account for new flag that reduces
false positives by not recognizing jinja code changes as a
`state:modified`

## Checklist
- [ ] I have reviewed the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [ ] The topic I'm writing about is for specific dbt version(s) and I
have versioned it according to the [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and/or [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content)
guidelines.
- [ ] I have added checklist item(s) to this list for anything anything
that needs to happen before this PR is merged, such as "needs technical
review" or "change base branch."
<!--
PRE-RELEASE VERSION OF dbt (if so, uncomment):
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
<!--
ADDING OR REMOVING PAGES (if so, uncomment):
- [ ] Add/remove page in `website/sidebars.js`
- [ ] Provide a unique filename for new pages
- [ ] Add an entry for deleted pages in `website/vercel.json`
- [ ] Run link testing locally with `npm run build` to update the links
that point to deleted pages
-->

---------

Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
Co-authored-by: Grace Goheen <53586774+graciegoheen@users.noreply.github.com>
---
 .../state-comparison-caveats.md               | 23 ++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/website/docs/reference/node-selection/state-comparison-caveats.md b/website/docs/reference/node-selection/state-comparison-caveats.md
index b0abde03aa..634bd92db0 100644
--- a/website/docs/reference/node-selection/state-comparison-caveats.md
+++ b/website/docs/reference/node-selection/state-comparison-caveats.md
@@ -16,7 +16,16 @@ dbt will mark modified any resource that depends on a changed macro, or on a mac
 
 ### Vars
 
-If a model uses a `var` or `env_var` in its definition, dbt is unable today to identify that lineage in such a way that it can include the model in `state:modified` because the `var` or `env_var` value has changed. It's likely that the model will be marked modified if the change in variable results in a different configuration.
+<VersionBlock lastVersion="1.8">
+
+If a model uses a `var` or `env_var` in its definition, dbt Core 1.8 and earlier are unable today to identify that lineage in such a way that it can include the model in `state:modified` because the `var` or `env_var` value has changed. It's likely that the model will be marked modified if the change in variable results in a different configuration.
+</VersionBlock>
+
+<VersionBlock firstVersion="1.9">
+
+Beginning in dbt Core 1.9, when you set the `state_modified_compare_vars` [behavior flag](/reference/global-configs/behavior-changes#behavior-change-flags) to `True` and a model uses a `var` or `env_var` in its definition, dbt will identify that lineage in such a way that it will include the model in `state:modified` when the `var` or `env_var` value has changed. 
+
+</VersionBlock>
 
 ### Tests
 
@@ -44,12 +53,19 @@ dbt test -s "state:modified" --exclude "test_name:relationships"
 
 ### False positives
 
+<VersionBlock firstVersion="1.9">
+
+To reduce false positives during `state:modified` selection due to env-aware logic, you can set the `state_modified_compare_more_unrendered` [behavior flag](/reference/global-configs/behavior-changes#behavior-change-flags) to `True`. 
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
 State comparison works by identifying discrepancies between two manifests.  Those discrepancies could be the result of:
 
 1. Changes made to a project in development
-2. Env-aware logic that causes different behavior based on the `target`, env vars, etc.
+2. Env-aware logic that causes different behavior based on the `target`, env vars, etc., which can be avoided if you upgrade to dbt Core 1.9 and set the `state_modified_compare_more_unrendered` [behavior flag](/reference/global-configs/behavior-changes#behavior-change-flags) to `True`. 
 
-State comparison detects env-aware config in `dbt_project.yml`. This target-based config registers as a modification:
+State comparison detects env-aware config in `dbt_project.yml`. This target-based config won't register as a modification:
 
 <File name='dbt_project.yml'>
 
@@ -73,6 +89,7 @@ That means the following config—functionally identical to the snippet above—
     materialized = ('table' if target.name == 'prod' else 'view')
 ) }}
 ```
+</VersionBlock>
 
 ### Final note