Initial "wireframe" for model contracts

website/dbt-versions.js

@@ -1,4 +1,9 @@
 exports.versions = [
+  {
+    version: "1.5",
+    EOLDate: "2024-04-26",
+    isPrerelease: true,
+  },
   {
     version: "1.4",
     EOLDate: "2024-01-25",
@@ -22,6 +27,34 @@ exports.versions = [
 ]
 
 exports.versionedPages = [
+  {
+    "page": "docs/collaborate/publish/model-contracts",
+    "firstVersion": "1.5",
+  },
+  {
+    "page": "docs/collaborate/publish/model-access",
+    "firstVersion": "1.5",
+  },
+  {
+    "page": "docs/collaborate/publish/model-versions",
+    "firstVersion": "1.5",
+  },
+  {
+    "page": "reference/resource-configs/contract",
+    "firstVersion": "1.5",
+  },
+  {
+    "page": "reference/resource-properties/constraints",
+    "firstVersion": "1.5",
+  },
+  {
+    "page": "reference/dbt-jinja-functions/local-md5",
+     "firstVersion": "1.4",
+   },
+   {
+     "page": "reference/warehouse-setups/fal-setup",
+     "firstVersion": "1.3",
+   },
   {
     "page": "reference/dbt-jinja-functions/set",
     "firstVersion": "1.2",
@@ -50,12 +83,4 @@ exports.versionedPages = [
     "page": "reference/dbt-jinja-functions/print",
     "firstVersion": "1.1",
   },
-  {
-   "page": "reference/dbt-jinja-functions/local-md5",
-    "firstVersion": "1.4",
-  },
-  {
-    "page": "reference/warehouse-setups/fal-setup",
-    "firstVersion": "1.3",
-  },
 ]

website/docs/docs/collaborate/publish/model-access.md

@@ -0,0 +1,64 @@
+---
+title: "Model access"
+id: model-access
+sidebar_label: "Model access"
+description: "Define model access with group capabilities"
+---
+
+:::info Beta functionality
+This functionality is new in v1.5. These docs exist to provide a high-level overview of what's to come. The specific syntax is liable to change.
+
+For more details and to leave your feedback, join the GitHub discussion:
+["Model groups & access" (dbt-core#6730)](https://github.com/dbt-labs/dbt-core/discussions/6730)
+:::
+
+## Related documentation
+* Coming soon: `groups`
+* Coming soon: `access` modifiers
+
+### Groups
+
+Models can be grouped under a common designation with a shared owner.
+
+Why define model `groups`?
+- It turns implicit relationships into an explicit grouping
+- It enables you to mark specific models as "private" for use _only_ within that group
+
+### Access modifiers
+
+Some models (not all) are designed to be shared across groups.
+
+https://en.wikipedia.org/wiki/Access_modifiers
+
+| Keyword   | Meaning              |
+|-----------|----------------------|
+| private   | same group           |
+| protected | same project/package |
+| public    | everybody           |
+
+By default, all models are "protected." This means that other models in the same project can reference them.
+
+:::info Under construction 🚧
+The following syntax is currently under review and does not work.
+:::
+
+<File name="models/marts/customers.yml">
+
+```yaml
+groups:
+  - name: cx
+    owner:
+      name: Customer Success Team
+      email: cx@jaffle.shop
+
+models:
+  - name: dim_customers
+    group: cx
+    access: public
+  # this is an intermediate transformation -- relevant to the CX team only
+  - name: int__customer_history_rollup
+    group: cx
+    access: private
+```
+
+</File>

website/docs/docs/collaborate/publish/model-contracts.md

@@ -0,0 +1,89 @@
+---
+title: "Model contracts"
+id: model-contracts
+sidebar_label: "Model contracts"
+description: "Model contracts define a set of parameters validated during transformation"
+---
+
+:::info Beta functionality
+This functionality is new in v1.5. These docs provide a high-level overview of what's to come. The specific syntax is liable to change.
+
+For more details and to leave your feedback, join the GitHub discussion:
+* ["Model contracts" (dbt-core#6726)](https://github.com/dbt-labs/dbt-core/discussions/6726)
+:::
+
+## Related documentation
+* [`contract`](resource-configs/contract)
+* [`columns`](resource-properties/columns)
+* [`constraints`](resource-properties/constraints)
+
+## Why define a contract?
+
+Defining a dbt model is as easy as writing a SQL `select` statement or a Python Data Frame transformation. Your query naturally produces a dataset with columns of names and types based on the columns you select and the transformations you apply.
+
+While this is ideal for quick and iterative development, for some models, constantly changing the shape of its returned dataset poses a risk when other people and processes are querying that model. It's better to define a set of upfront parameters about the shape of your model. We call this set of parameters a "contract." While building your model, dbt will verify that your model's transformation will produce a dataset matching up with its contract, or it will fail to build.
+
+## How to define a contract
+
+Let's say you have a model with a query like:
+
+<File name="models/marts/dim_customers.sql">
+
+```sql
+-- lots of SQL
+
+final as (
+
+    select
+        -- lots of columns
+    from ...
+
+)
+
+select * from final
+```
+</File>
+
+Your contract _must_ include every column's `name` and `data_type` (where `data_type` matches the type your data platform understands). If your model is materialized as `table` or `incremental`, you may optionally specify that certain columns must be `not_null` (containing zero null values). Depending on your data platform, you may also be able to define additional `constraints` enforced while the model is being built.
+
+Finally, you configure your model with `contract: true`.
+
+<File name="models/marts/customers.yml">
+
+```yaml
+models:
+  - name: dim_customers
+    config:
+      contract: true
+    columns:
+      - name: customer_id
+        data_type: int
+        not_null: true
+      - name: customer_name
+        data_type: string
+        ...
+```
+
+</File>
+
+When building a model with a defined contract, dbt will do two things differently:
+1. dbt will run a prerequisite check to ensure that the model's query will return a set of columns with names and data types matching the ones you have defined.
+2. dbt will pass the column names, types, `not_null`, and other constraints into the DDL statements it submits to the data platform, which will be enforced while building the table.
+
+## FAQs
+
+### Which models should have contracts?
+
+Any model can define a contract. Defining contracts for “public” models that are being shared with other groups, teams, and (soon) dbt projects is especially important.
+
+### How are contracts different from tests?
+
+A model's contract defines the **shape** of the returned dataset.
+
+[Tests](tests) are a more flexible mechanism for validating the content of your model. So long as you can write the query, you can run the test. Tests are also more configurable via `severity` and custom thresholds and are easier to debug after finding failures. The model has already been built, and the relevant records can be materialized in the data warehouse by [storing failures](resource-configs/store_failures).
+
+In blue/green deployments (docs link TK), ... <!-- TODO write more here -->
+
+In parallel for software APIs:
+- The structure of the API response is the contract
+- Quality and reliability ("uptime") are also **crucial**, but not part of the contract per se.

website/docs/docs/collaborate/publish/model-versions.md

@@ -0,0 +1,31 @@
+---
+title: "Model versions"
+id: model-versions
+sidebar_label: "Model versions"
+description: "Version models to help with lifecycle management"
+---
+
+:::info Beta functionality
+This functionality is new in v1.5. These docs exist to provide a high-level overview of what's to come. The specific syntax is liable to change.
+
+For more details and to leave your feedback, check out the GitHub discussion:
+* ["Model versions" (dbt-core#6736)](https://github.com/dbt-labs/dbt-core/discussions/6736)
+:::
+
+API versioning is a _complex_ problem in software engineering. It's also essential. Our goal is to _overcome obstacles to transform a complex problem into a reality_.
+
+## Related documentation
+* Coming soon: `version` & `latest` (_not_ [this one](project-configs/version))
+* Coming soon: `deprecation_date`
+
+## Why version a model?
+
+If a model defines a ["contract"](model-contracts) (a set of guarantees for its structure), it's also possible to change that model's contract in a way that "breaks" the previous set of parameters.
+
+One approach is to force every model consumer to immediately handle the breaking change when it's deployed to production. While this may work at smaller organizations or while iterating on an immature set of data models, it doesn’t scale well beyond that.
+
+Instead, the model owner can create a **new version** and provide a **deprecation window**, during which consumers can migrate from the old version to the new.
+
+In the meantime, anywhere that model is used downstream, it can be referenced at a specific version.
+
+When a model approaches its deprecation date, consumers of that model will be notified about it. When the date is reached, it goes away.

website/docs/guides/migration/versions/02-upgrading-to-v1.5.md

@@ -0,0 +1,57 @@
+---
+title: "Trying v1.5 (prerelease)"
+description: New features and changes in dbt Core v1.5
+---
+
+:::info
+v1.5 is currently available as a **beta prerelease.** Availability in dbt Cloud coming soon!
+:::
+
+### Resources
+
+- [Changelog](https://github.com/dbt-labs/dbt-core/blob/main/CHANGELOG.md)
+- [CLI Installation guide](/docs/get-started/installation)
+- [Cloud upgrade guide](/docs/dbt-versions/upgrade-core-in-cloud)
+- [Release schedule](https://github.com/dbt-labs/dbt-core/issues/6715)
+
+**Planned final release:** April 26, 2023
+
+dbt Core v1.5 is a feature release, with two big additions planned:
+1. **"Models as APIs,"** the first phase of [multi-project deployments](https://github.com/dbt-labs/dbt-core/discussions/6725)
+2. An initial **Python API for dbt-core,** supporting programmatic invocations at parity with the CLI
+
+## What to know before upgrading
+
+dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new).
+
+### Breaking changes
+
+As part of our refactor of `dbt-core` internals, we need to make some **very precise** changes to runtime configuration. The net result of these changes is more sensible configuration options, clearer documentation, cleaner APIs, and a more legible codebase.
+
+Wherever possible, we will aim to provide backwards compatibility and deprecation warnings for at least one minor version, before actually removing the old functionality. In those cases, we still reserve the right to fully remove the backward-compatible functionality in a future v1.x minor version of `dbt-core`.
+
+Changes planned for v1.5:
+- Renaming ["global configs"](global-configs) for consistency ([dbt-core#6903](https://github.com/dbt-labs/dbt-core/issues/6903))
+- Moving `log-path` and `target-path` out of `dbt_project.yml`, for consistency with other global configs ([dbt-core#6882](https://github.com/dbt-labs/dbt-core/issues/6882))
+
+### For consumers of dbt artifacts (metadata)
+
+The manifest schema version will be updated to `v9`. Specific changes to be noted here.
+
+### For maintainers of adapter plugins
+
+Forthcoming: GH discussion detailing interface changes, and offering a forum for Q&A
+
+## New and changed documentation
+
+:::caution Under construction 🚧
+More to come!
+:::
+
+### Publishing models as APIs
+- [Model contracts](model-contracts) ([#2839](https://github.com/dbt-labs/docs.getdbt.com/issues/2839))
+- [Model access](model-access) ([#2840](https://github.com/dbt-labs/docs.getdbt.com/issues/2840))
+- [Model versions](model-versions) ([#2841](https://github.com/dbt-labs/docs.getdbt.com/issues/2841))
+
+### dbt-core Python API
+- Auto-generated documentation ([#2674](https://github.com/dbt-labs/docs.getdbt.com/issues/2674)) for dbt-core CLI & Python API for programmatic invocations

website/docs/reference/model-configs.md

@@ -105,6 +105,7 @@ models:
     [+](plus-prefix)[full_refresh](full_refresh): <boolean>
     [+](plus-prefix)[meta](meta): {<dictionary>}
     [+](plus-prefix)[grants](grants): {<dictionary>}
+    [+](plus-prefix)[contract](contract): true | false
 
 ```
 
@@ -134,6 +135,7 @@ models:
       [full_refresh](full_refresh): <boolean>
       [meta](meta): {<dictionary>}
       [grants](grants): {<dictionary>}
+      [contract](contract): true | false
 ```
 
 </File>
@@ -157,8 +159,9 @@ models:
     [schema](resource-configs/schema)="<string>",
     [alias](resource-configs/alias)="<string>",
     [persist_docs](persist_docs)={<dict>},
-    [meta](meta)={<dict>}
-    [grants](grants)={<dict>}
+    [meta](meta)={<dict>},
+    [grants](grants)={<dict>},
+    [contract](contract)=true | false
 ) }}
 
 ```