From b6351b13c151f0d3d27d8513563c60f1fa81d34f Mon Sep 17 00:00:00 2001
From: Mike Alfare <13974384+mikealfare@users.noreply.github.com>
Date: Thu, 19 Sep 2024 10:21:38 -0400
Subject: [PATCH] Add behavior change flag docs for adapter maintainers (#6092)
## What are you changing in this pull request and why?
We added behavior flags for adapter maintainers to use on first- and
third-party adapters. This PR adds documentation explaining how to
configure and use behavior flags.
## Checklist
- [x] 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.
- [x] 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.
- [x] 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."
- [x] Approval by Product (@amychen1776)
---------
Co-authored-by: Amy Chen <46451573+amychen1776@users.noreply.github.com>
Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com>
---
website/docs/guides/adapter-creation.md | 102 ++++++++++++++++++++++++
1 file changed, 102 insertions(+)
diff --git a/website/docs/guides/adapter-creation.md b/website/docs/guides/adapter-creation.md
index f737afa0392..066d27a7aaa 100644
--- a/website/docs/guides/adapter-creation.md
+++ b/website/docs/guides/adapter-creation.md
@@ -556,6 +556,108 @@ While much of dbt's adapter-specific functionality can be modified in adapter ma
See [this GitHub discussion](https://github.com/dbt-labs/dbt-core/discussions/5468) for information on the macros required for `GRANT` statements:
+### Behavior change flags
+
+Starting in `dbt-adapters==1.5.0` and `dbt-core==1.8.7`, adapter maintainers can implement their own behavior change flags. Refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes)for more information.
+
+Behavior Flags are not intended to be long-living feature flags. They should be implemented with the expectation that the behavior will be the default within an expected period of time. To implement a behavior change flag, you must provide a name for the flag, a default setting (`True` / `False`), an optional source, and a description and/or a link to the flag's documentation on docs.getdbt.com.
+
+We recommend having a description and documentation link whenever possible. The description and/or docs should provide end users context for why the flag exists, why they may see a warning, and why they may want to utilize the behavior flag. Behavior change flags can be implemented by overwriting `_behavior_flags()` on the adapter in `impl.py`:
+
+
+
+```python
+class ABCAdapter(BaseAdapter):
+ ...
+ @property
+ def _behavior_flags(self) -> List[BehaviorFlag]:
+ return [
+ {
+ "name": "enable_new_functionality_requiring_higher_permissions",
+ "default": False,
+ "source": "dbt-abc",
+ "description": (
+ "The dbt-abc adapter is implementing a new method for sourcing metadata. "
+ "This is a more performant way for dbt to source metadata but requires higher permissions on the platform. "
+ "Enabling this without granting the requisite permissions will result in an error. "
+ "This feature is expected to be required by Spring 2025."
+ ),
+ "docs_url": "https://docs.getdbt.com/reference/global-configs/behavior-changes#abc-enable_new_functionality_requiring_higher_permissions",
+ }
+ ]
+```
+
+
+
+Once a behavior change flag has been implemented, it can be referenced on the adapter both in `impl.py` and in Jinja macros:
+
+
+
+```python
+class ABCAdapter(BaseAdapter):
+ ...
+ def some_method(self, *args, **kwargs):
+ if self.behavior.enable_new_functionality_requiring_higher_permissions:
+ # do the new thing
+ else:
+ # do the old thing
+```
+
+
+
+
+
+```sql
+{% macro some_macro(**kwargs) %}
+ {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions %}
+ {# do the new thing #}
+ {% else %}
+ {# do the old thing #}
+ {% endif %}
+{% endmacro %}
+```
+
+
+
+Every time the behavior flag evaluates to `False,` it warns the user, informing them that a change will occur in the future.
+
+This warning doesn't display when the flag evaluates to `True` as the user is already in the new experience.
+
+Recognizing that the warnings can be disruptive and are not always necessary, you can evaluate the flag without triggering the warning. Simply append `.no_warn` to the end of the flag.
+
+
+
+
+```python
+ class ABCAdapter(BaseAdapter):
+ ...
+ def some_method(self, *args, **kwargs):
+ if self.behavior.enable_new_functionality_requiring_higher_permissions.no_warn:
+ # do the new thing
+ else:
+ # do the old thing
+```
+
+
+
+
+
+```sql
+{% macro some_macro(**kwargs) %}
+ {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions.no_warn %}
+ {# do the new thing #}
+ {% else %}
+ {# do the old thing #}
+ {% endif %}
+{% endmacro %}
+```
+
+
+
+It's best practice to evaluate a behavior flag as few times as possible. This will make it easier to remove once the behavior change has matured.
+
+As a result, evaluating the flag earlier in the logic flow is easier. Then, take either the old or the new path. While this may create some duplication in code, using behavior flags in this way provides a safer way to implement a change, which we are already admitting is risky or even breaking in nature.
+
### Other files
#### `profile_template.yml`