Updates on model namespacing & uniqueness (#3604)

resolves #3571

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

Starting in v1.6, model names can be duplicated across different
namespaces (packages/projects). They must still be unique within one
package/project.

This requires updates to:
- our FAQ on model name uniqueness
- two-argument `ref`
- note on snapshot name uniqueness
- (I'm sure I've missed some places)

## Checklist
- [x] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [x] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/guides/migration/versions)
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
and [About
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
so my content adheres to these guidelines.
- [x] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

website/docs/faqs/Models/unique-model-names.md

@@ -6,6 +6,20 @@ id: unique-model-names
 
 ---
 
-Yes! To build dependencies between models, you need to use the `ref` function. The `ref` function only takes one argument — the model name (i.e. the filename). As a result, these model names need to be unique, _even if they are in distinct folders_.
+<VersionBlock firstVersion="1.6">
+
+Within one project: yes! To build dependencies between models, you need to use the `ref` function, and pass in the model name as an argument. dbt uses that model name to uniquely resolve the `ref` to a specific model. As a result, these model names need to be unique, _even if they are in distinct folders_.
+
+A model in one project can have the same name as a model in another project (installed as a dependency). dbt uses the project name to uniquely identify each model. We call this "namespacing." If you `ref` a model with a duplicated name, it will resolve to the model within the same namespace (package or project), or raise an error because of an ambiguous reference. Use [two-argument `ref`](/reference/dbt-jinja-functions/ref#two-argument-variant) to disambiguate references by specifying the namespace.
+
+Those models will still need to land in distinct locations in the data warehouse. Read the docs on [custom aliases](/docs/build/custom-aliases) and [custom schemas](/docs/build/custom-schemas) for details on how to achieve this.
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.5">
+
+Yes! To build dependencies between models, you need to use the `ref` function, and pass in the model name as an argument. dbt uses that model name to uniquely resolve the `ref` to a specific model. As a result, these model names need to be unique, _even if they are in distinct folders_.
 
 Often, this question comes up because users want to give two models the same name in their warehouse, splitting them across separate schemas (e.g. `stripe.users` and `app.users`). Checkout the docs on [custom aliases](/docs/build/custom-aliases) and [custom schemas](/docs/build/custom-schemas) to achieve this.
+
+</VersionBlock>

website/docs/guides/migration/versions/01-upgrading-to-v1.6.md

@@ -27,7 +27,7 @@ dbt Labs is committed to providing backward compatibility for all versions 1.x,
 
 ## New and changed documentation
 
-**Coming Soon**
+[**Namespacing:**](/faqs/Models/unique-model-names) Model names can be duplicated across different namespaces (packages/projects), so long as they are unique within each package/project. We strongly encourage using [two-argument `ref`](/reference/dbt-jinja-functions/ref#two-argument-variant) when referencing a model from a different package/project.
 
 ### Quick hits
 

website/docs/reference/dbt-jinja-functions/ref.md

@@ -73,13 +73,21 @@ select * from {{ ref('model_name') }}
 
 ### Two-argument variant
 
-There is also a two-argument variant of the `ref` function. With this variant, you can pass both a package name and model name to `ref` to avoid ambiguity. This functionality is not commonly required for typical dbt usage.
+There is also a two-argument variant of the `ref` function. With this variant, you can pass both a namespace (project or package) and model name to `ref` to avoid ambiguity.
 
 ```sql
-select * from {{ ref('package_name', 'model_name') }}
+select * from {{ ref('project_or_package', 'model_name') }}
 ```
 
-**Note:** The `package_name` should only include the name of the package, not the maintainer. For example, if you use the [`fivetran/stripe`](https://hub.getdbt.com/fivetran/stripe/latest/) package, type `stripe` in that argument, and not `fivetran/stripe`.
+We recommend using two-argument `ref` any time you are referencing a model defined in a different package or project. While not required in all cases, it's more explicit for you, for dbt, and for future readers of your code.
+
+<VersionBlock firstVersion="1.6">
+
+We especially recommend using two-argument `ref` to avoid ambiguity, in cases where a model name is duplicated across multiple projects or installed packages. If you use one-argument `ref` (just the `model_name`), dbt will look for a model by that name in the same namespace (package or project); if it finds none, it will raise an error.
+
+</VersionBlock>
+
+**Note:** The `project_or_package` should match the `name` of the project/package, as defined in its `dbt_project.yml`. This might be different from the name of the repository. It never includes the repository's organization name. For example, if you use the [`fivetran/stripe`](https://hub.getdbt.com/fivetran/stripe/latest/) package, the package name is `stripe`, not `fivetran/stripe`.
 
 ### Forcing Dependencies
 

website/docs/reference/resource-configs/snapshot_name.md

@@ -17,7 +17,7 @@ description: "Snapshot-name - Read this in-depth guide to learn about configurat
 
 The name of a snapshot, as defined in the `{% snapshot %}` block header. This name is used when selecting from a snapshot using the [`ref` function](/reference/dbt-jinja-functions/ref)
 
-This name must not conflict with any other snapshot names, or any model names.
+This name must not conflict with the name of any other "refable" resource (models, seeds, other snapshots) defined in this project or package.
 
 The name does not need to match the file name. As a result, snapshot filenames do not need to be unique.