Add behavior change flag docs for adapter maintainers

[mikealfare]

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

• I have reviewed the Content style guide 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 and/or version a block 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."
• Approval by Product (@amychen1776)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-getdbt-com	✅ Ready (Inspect)	Visit Preview	Sep 19, 2024 2:18pm

[amychen1776]

Suggested change

	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.
	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.

[amychen1776]

Also what is source?

[mikealfare]

source is basically a namespace. I would list the adapter as the source for adapter behavior flags. But the framework can be used elsewhere, so I don't force that. I also provide a default that takes the calling module, so that even if the maintainer does not add a source, there's still something that we can use to differentiate flags with the same name across multiple adapters (or not in an adapter at all). I wanted to try and automate it since it would feel silly to need to specify the adapter for every flag. We could probably be smarter than this and set it in BaseAdapter somehow when they get registered.

[amychen1776]

It's best practice to evaluate a behavior flag as few times as possible.

what does this mean?

[mikealfare]

Don't pepper the code with a bunch individual checks like it's a configuration. It should truly represent "a legacy way" and "a novel way".

The dbt-redshift example is a good one. Depending on whether we use the SDK or not, we either call the macro, or we call the SDK. We check the flag once.

In more complicated scenarios this may not be possible. Take Iceberg support for example. We need to check the flag in list relations and we also need to check it when creating a table in the create table macro. So we need to check it twice, there's really no way around that. But let's look at the create table macro in particular. We should just have two versions of that macro, the legacy version without Iceberg and the novel way with Iceberg; these are gated by the flag. That's good.

Using two completely different versions of the code will result in a lot of duplicated code though. Both versions need a name, they need to put the sql at the end, they have shared options like warehouse, etc. But there are multiple points where they differ as well. There are different config options like external_volume. One uses create table my_table as... and the other uses create iceberg table my_table as.... So there will be an intuitive push towards DRY code where you can embed a check inside the macro at each point where it differs. That's not good. The behavior flag is becoming part of the code, and can more easily contribute to bugs in the code, in particular in the legacy code which was supposed to be gated from this whole change in the first place.

[amychen1776]

[matthewshaver]

Thank you @mikealfare !