Revisions & additions to Model Versions (#3232)

[Preview: Collaborate with others > Model governance > Model
versions](https://deploy-preview-3232--docs-getdbt-com.netlify.app/docs/collaborate/govern/model-versions)

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

We've written the minimal viable reference docs for this feature. I want
to offer some more opinionated guidance & framing, and gesture in the
direction of some best practices:
- **Don't** create a new version for every model change
- **Do** actually sunset/deprecate your old model versions

This does require a more personal tone, and a sense of future direction,
than a lot of other (more-established) documentation. Very open to
feedback.

---------

Co-authored-by: mirnawong1 <[email protected]>

_redirects

@@ -279,6 +279,7 @@ docs/dbt-cloud/using-dbt-cloud/cloud-model-timing-tab /docs/deploy/dbt-cloud-job
 /docs/artifacts /docs/dbt-cloud/using-dbt-cloud/artifacts 301
 /docs/bigquery-configs /reference/resource-configs/bigquery-configs 301
 /reference/resource-properties/docs /reference/resource-configs/docs 301
+/reference/resource-properties/latest-version /reference/resource-properties/latest_version 301
 /docs/building-a-dbt-project/building-models/bigquery-configs /reference/resource-configs/bigquery-configs 301
 /docs/building-a-dbt-project/building-models/configuring-models /reference/model-configs
 /docs/building-a-dbt-project/building-models/enable-and-disable-models /reference/resource-configs/enabled 301

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

@@ -6,7 +6,7 @@ description: "Define model access with group capabilities"
 ---
 
 :::info New functionality
-This functionality is new in v1.5.
+This functionality is new in v1.5 — if you have thoughts, participate in [the discussion on GitHub](https://github.com/dbt-labs/dbt-core/discussions/6730)!
 :::
 
 :::info "Model access" is not "User access"

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

@@ -6,7 +6,7 @@ description: "Model contracts define a set of parameters validated during transf
 ---
 
 :::info New functionality
-This functionality is new in v1.5.
+This functionality is new in v1.5 — if you have thoughts, participate in [the discussion on GitHub](https://github.com/dbt-labs/dbt-core/discussions/6726)!
 :::
 
 ## Related documentation

website/docs/reference/model-properties.md

@@ -16,7 +16,7 @@ models:
     [description](description): <markdown_string>
     [docs](/reference/resource-configs/docs):
       show: true | false
-    [latest_version](resource-properties/latest-version): <version_identifier>
+    [latest_version](resource-properties/latest_version): <version_identifier>
     [access](resource-properties/access): private | protected | public
     [config](resource-properties/config):
       [<model_config>](model-configs): <config_value>

website/docs/reference/resource-properties/versions.md

@@ -16,15 +16,15 @@ models:
       - v: <version_identifier> # required
         defined_in: <file_name> # optional -- default is <model_name>_v<v>
         columns:
-          # include/exclude columns from the top-level model properties
+          # specify all columns, or include/exclude columns from the top-level model yaml definition
           - [include](resource-properties/include-exclude): <include_value>
             [exclude](resource-properties/include-exclude): <exclude_list>
           # specify additional columns
           - name: <column_name> # required
       - v: ...
 
     # optional
-    [latest_version](resource-properties/latest-version): <version_identifier> 
+    [latest_version](resource-properties/latest_version): <version_identifier> 
 ```
 
 </File>
@@ -35,24 +35,29 @@ The standard convention for naming model versions is `<model_name>_v<v>`. This h
 
 The version identifier for a version of a model. This value can be numeric (integer or float), or any string.
 
-The value of the version identifier is used to order versions of a model relative to one another. If a versioned model does _not_ explicitly configure a [`latest_version`](resource-properties/latest-version), the highest version number is used as the latest version to resolve `ref` calls to the model without a `version` argument.
+The value of the version identifier is used to order versions of a model relative to one another. If a versioned model does _not_ explicitly configure a [`latest_version`](resource-properties/latest_version), the highest version number is used as the latest version to resolve `ref` calls to the model without a `version` argument.
 
-In general, we recommend that you use a simple "major versioning" scheme for your models: `v1`, `v2`, `v3`, etc, where each version represents a breaking change from previous versions. However, you are welcome to use other versioning schemes.
+In general, we recommend that you use a simple "major versioning" scheme for your models: `1`, `2`, `3`, and so on, where each version reflects a breaking change from previous versions. You are able to use other versioning schemes. dbt will sort your version identifiers alphabetically if the values are not all numeric. You should **not** include the letter `v` in the version identifier, as dbt will do that for you.
 
 ### `defined_in`
 
 The name of the model file (excluding the file extension, e.g. `.sql` or `.py`) where the model version is defined.
 
-If `defined_in` is not specified, dbt searches for the definition of a versioned model in a model file named `<model_name>_v<v>`. Model file names must be globally unique, even when defining versioned implementations of a model with a different name.
+If `defined_in` is not specified, dbt searches for the definition of a versioned model in a model file named `<model_name>_v<v>`. The **latest** version of a model may also be defined in a file named `<model_name>`, without the version suffix. Model file names must be globally unique, even when defining versioned implementations of a model with a different name.
 
-### Alias
+### `alias`
 
-The default `alias` for a versioned model is `<model_name>_v<v>`.
+The default resolved `alias` for a versioned model is `<model_name>_v<v>`. The logic for this is encoded in the `generate_alias_name` macro.
 
 This default can be overwritten in two ways:
-- Configuring a custom `alias` within the version yaml
-- Overwriting dbt's `generate_alias_name` macro, to use different behavior when `node.version`
+- Configuring a custom `alias` within the version yaml, or the versioned model's definition
+- Overwriting dbt's `generate_alias_name` macro, to use different behavior based on `node.version`
 
 See ["Custom aliases"](https://docs.getdbt.com/docs/build/custom-aliases) for more details.
 
-Setting a different value of `defined_in` does **not** automatically change the `alias` of the model to match. The two are determined independently. 
+Note that the value of `defined_in` and the `alias` configuration of a model are not coordinated, except by convention. The two are declared and determined independently.
+
+### Our recommendations
+- Follow a consistent naming convention for model versions and aliases.
+- Use `defined_in` and `alias` only if you have good reason.
+- Create a view that always points to the latest version of your model. You can automate this for all versioned models in your project with an `on-run-end` hook. For more details, read the full docs on ["Model versions"](model-versions#configuring-database-location-with-alias)

website/sidebars.js

@@ -459,7 +459,7 @@ const sidebarSettings = {
             "reference/resource-properties/config",
             "reference/resource-properties/constraints",
             "reference/resource-properties/description",
-            "reference/resource-properties/latest-version",
+            "reference/resource-properties/latest_version",
             "reference/resource-properties/include-exclude",
             "reference/resource-properties/quote",
             "reference/resource-properties/tests",