From aadc82b036636ede4f6a64c47bad3f8a7028c7ea Mon Sep 17 00:00:00 2001 From: Mike Alfare Date: Wed, 18 Sep 2024 18:48:09 -0400 Subject: [PATCH 1/4] add behavior change flag docs for adapter maintainers --- website/docs/guides/adapter-creation.md | 99 +++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/website/docs/guides/adapter-creation.md b/website/docs/guides/adapter-creation.md index f737afa0392..3804bbeb5c5 100644 --- a/website/docs/guides/adapter-creation.md +++ b/website/docs/guides/adapter-creation.md @@ -556,6 +556,105 @@ 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`, adapter maintainers have the ability to implement their own behavior change flags. For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). +To implement a behavior change flag, provide a name, a default setting (`True` / `False`), and optional source, and either a description or a link to the flag's documentation on docs.getdbt.com. +The description and/or docs should provide end users with context for why the flag exists, why they may see a warning, and why they may want to override the default. +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. " + "While we feel this is a better way to source metadata, it does require 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 will fire a warning to the user informing them that there will be a future change. +This warning doesn't fire when the flag evaluates to `True` as the user is already in the new experience. +The warnings can be noisy, and isn't always desired. To evaluate the flag without firing the warning, 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, it tends to be easier to evaluate the flag earlier in logic flow, then take either the old path 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` From 6d644a7928e3a843d13f6446ff1f0980bec17477 Mon Sep 17 00:00:00 2001 From: Mike Alfare Date: Wed, 18 Sep 2024 19:47:14 -0400 Subject: [PATCH 2/4] add the dbt-core version that supports behavior flags --- website/docs/guides/adapter-creation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/guides/adapter-creation.md b/website/docs/guides/adapter-creation.md index 3804bbeb5c5..6325071b94b 100644 --- a/website/docs/guides/adapter-creation.md +++ b/website/docs/guides/adapter-creation.md @@ -558,7 +558,8 @@ See [this GitHub discussion](https://github.com/dbt-labs/dbt-core/discussions/54 ### Behavior change flags -Starting in `dbt-adapters==1.5`, adapter maintainers have the ability to implement their own behavior change flags. For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). +Starting in `dbt-adapters==1.5.0` and `dbt-core==1.8.7`, adapter maintainers have the ability to implement their own behavior change flags. +For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). To implement a behavior change flag, provide a name, a default setting (`True` / `False`), and optional source, and either a description or a link to the flag's documentation on docs.getdbt.com. The description and/or docs should provide end users with context for why the flag exists, why they may see a warning, and why they may want to override the default. Behavior change flags can be implemented by overwriting `_behavior_flags()` on the adapter in `impl.py`: From cd9ecd477be15fe780745ce136f82b5f74ab7604 Mon Sep 17 00:00:00 2001 From: Mike Alfare <13974384+mikealfare@users.noreply.github.com> Date: Wed, 18 Sep 2024 20:05:43 -0400 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Amy Chen <46451573+amychen1776@users.noreply.github.com> --- website/docs/guides/adapter-creation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/guides/adapter-creation.md b/website/docs/guides/adapter-creation.md index 6325071b94b..dc23fd82853 100644 --- a/website/docs/guides/adapter-creation.md +++ b/website/docs/guides/adapter-creation.md @@ -559,9 +559,9 @@ See [this GitHub discussion](https://github.com/dbt-labs/dbt-core/discussions/54 ### Behavior change flags Starting in `dbt-adapters==1.5.0` and `dbt-core==1.8.7`, adapter maintainers have the ability to implement their own behavior change flags. -For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). -To implement a behavior change flag, provide a name, a default setting (`True` / `False`), and optional source, and either a description or a link to the flag's documentation on docs.getdbt.com. -The description and/or docs should provide end users with context for why the flag exists, why they may see a warning, and why they may want to override the default. +For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). Behavior Flags are not intended to be long living feature flags and should be implemented with the expectation that the behavior will be default within an expected period of time. +To implement a behavior change flag, you will need to provide a name for the flag, a default setting (`True` / `False`), 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 with 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`: @@ -578,7 +578,7 @@ class ABCAdapter(BaseAdapter): "source": "dbt-abc", "description": ( "The dbt-abc adapter is implementing a new method for sourcing metadata. " - "While we feel this is a better way to source metadata, it does require higher permissions on the platform. " + "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." ), From d56214237004ebfa1e051291e06d94c9e78f8ce3 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Thu, 19 Sep 2024 10:10:40 -0400 Subject: [PATCH 4/4] Editorial changes --- website/docs/guides/adapter-creation.md | 26 +++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/website/docs/guides/adapter-creation.md b/website/docs/guides/adapter-creation.md index dc23fd82853..066d27a7aaa 100644 --- a/website/docs/guides/adapter-creation.md +++ b/website/docs/guides/adapter-creation.md @@ -558,11 +558,11 @@ See [this GitHub discussion](https://github.com/dbt-labs/dbt-core/discussions/54 ### Behavior change flags -Starting in `dbt-adapters==1.5.0` and `dbt-core==1.8.7`, adapter maintainers have the ability to implement their own behavior change flags. -For more information on what a behavior change is, please refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes). Behavior Flags are not intended to be long living feature flags and should be implemented with the expectation that the behavior will be default within an expected period of time. -To implement a behavior change flag, you will need to provide a name for the flag, a default setting (`True` / `False`), 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 with 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`: +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`: @@ -589,7 +589,7 @@ class ABCAdapter(BaseAdapter): -Once a behavior change flag has been implemented, it can be referenced on the adapter both in `impl.py` and in jinja macros: +Once a behavior change flag has been implemented, it can be referenced on the adapter both in `impl.py` and in Jinja macros: @@ -619,9 +619,12 @@ class ABCAdapter(BaseAdapter): -Every time the behavior flag evaluates to `False`, it will fire a warning to the user informing them that there will be a future change. -This warning doesn't fire when the flag evaluates to `True` as the user is already in the new experience. -The warnings can be noisy, and isn't always desired. To evaluate the flag without firing the warning, append `.no_warn` to the end of the flag: +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. + @@ -652,9 +655,8 @@ The warnings can be noisy, and isn't always desired. To evaluate the flag withou 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, it tends to be easier to evaluate the flag earlier in logic flow, then take either the old path 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. + +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