From 875a43b7b4bf277a76fbb473b49c2d2acf57ce6f Mon Sep 17 00:00:00 2001 From: Jeremy Cohen Date: Fri, 8 Sep 2023 12:20:07 +0200 Subject: [PATCH 1/8] Update use cases for 'local' packages --- website/docs/docs/build/packages.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index d4cebc7a6f0..fd3ebebfac0 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -284,18 +284,35 @@ packages: ### Local packages -Packages that you have stored locally can be installed by specifying the path to the project, like so: +A "local" package is another dbt project that you have access to from within the local file system. It can be installed by specifying the path to the project. The best-supported pattern is when the project is nested within a subdirectory, relative to the current project's directory. ```yaml packages: - - local: /opt/dbt/redshift # use a local path + - local: relative/path/to/subdirectory ``` -Local packages should only be used for specific situations, for example, when testing local changes to a package. +Other patterns may work in some cases, but not always. For example, if you install this project as a package elsewhere, or try running it on a different system, the relative and absolute paths will yield the same results. + + + +```yaml +packages: + # not recommended - these support for these patterns vary + - local: /../../redshift # relative path to a parent directory + - local: /opt/dbt/redshift # absolute path on the system +``` + + + +As such, there are a few specific use cases where a "local" package is recommended: +1. A monorepo containing multiple projects, each nested in a subdirectory. "Local" packages enable combining projects together, for coordinated development and deployment. +2. Testing changes to one project/package within the context of a downstream project/package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter, enabling quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. +3. A nested project that defines fixtures and tests for a project of utility macros — for example, [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests) + ## What packages are available? Check out [dbt Hub](https://hub.getdbt.com) to see the library of published dbt packages! From 768dbd7def72a363214344edd566351ab5cbda18 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:27:15 +0100 Subject: [PATCH 2/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index fd3ebebfac0..3f24e10bdfe 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -284,7 +284,7 @@ packages: ### Local packages -A "local" package is another dbt project that you have access to from within the local file system. It can be installed by specifying the path to the project. The best-supported pattern is when the project is nested within a subdirectory, relative to the current project's directory. +A "local" package is a dbt project accessible from your local file system. You can install it by specifying the project's path. It works best when you nest the project within a subdirectory relative to your current project's directory. From 696f025dc541eae36c79481e93131ec27e2dfd45 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:27:30 +0100 Subject: [PATCH 3/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index 3f24e10bdfe..833dbfcee63 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -301,7 +301,7 @@ Other patterns may work in some cases, but not always. For example, if you insta ```yaml packages: - # not recommended - these support for these patterns vary + # not recommended - the support for these patterns vary - local: /../../redshift # relative path to a parent directory - local: /opt/dbt/redshift # absolute path on the system ``` From d31edceca2ff8b7ebc294de63a7504fa6ba47be6 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:27:42 +0100 Subject: [PATCH 4/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index 833dbfcee63..851e898d5bd 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -308,7 +308,7 @@ packages: -As such, there are a few specific use cases where a "local" package is recommended: +There are a few specific use cases where we recommend using a "local" package: 1. A monorepo containing multiple projects, each nested in a subdirectory. "Local" packages enable combining projects together, for coordinated development and deployment. 2. Testing changes to one project/package within the context of a downstream project/package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter, enabling quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. 3. A nested project that defines fixtures and tests for a project of utility macros — for example, [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests) From 495b3ace5de4b909e2c8c79e2601426b1ba75a2d Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:27:49 +0100 Subject: [PATCH 5/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index 851e898d5bd..c8f980e45f2 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -309,7 +309,7 @@ packages: There are a few specific use cases where we recommend using a "local" package: -1. A monorepo containing multiple projects, each nested in a subdirectory. "Local" packages enable combining projects together, for coordinated development and deployment. +1. **Monorepo** — When you have multiple projects, each nested in a subdirectory, within a monorepo. "Local" packages allow you to combine projects for coordinated development and deployment. 2. Testing changes to one project/package within the context of a downstream project/package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter, enabling quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. 3. A nested project that defines fixtures and tests for a project of utility macros — for example, [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests) From 6fbb7dbfdd7a9806a5cd3308e6181fd8c613ac54 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:27:56 +0100 Subject: [PATCH 6/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index c8f980e45f2..12ae7d916ca 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -311,7 +311,7 @@ packages: There are a few specific use cases where we recommend using a "local" package: 1. **Monorepo** — When you have multiple projects, each nested in a subdirectory, within a monorepo. "Local" packages allow you to combine projects for coordinated development and deployment. 2. Testing changes to one project/package within the context of a downstream project/package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter, enabling quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. -3. A nested project that defines fixtures and tests for a project of utility macros — for example, [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests) +3. **Nested project** — When you have a nested project that defines fixtures and tests for a project of utility macros, like [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests). ## What packages are available? From 6e522feb2959d961cc4b5f7a0bf8c67bc754642d Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:28:01 +0100 Subject: [PATCH 7/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index 12ae7d916ca..4d0bfd808a1 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -310,7 +310,7 @@ packages: There are a few specific use cases where we recommend using a "local" package: 1. **Monorepo** — When you have multiple projects, each nested in a subdirectory, within a monorepo. "Local" packages allow you to combine projects for coordinated development and deployment. -2. Testing changes to one project/package within the context of a downstream project/package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter, enabling quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. +2. **Testing changes** — To test changes in one project or package within the context of a downstream project or package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter for quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python. 3. **Nested project** — When you have a nested project that defines fixtures and tests for a project of utility macros, like [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests). From 9d4f4912e0c6fabf598b7a931a93eec4ea336b00 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 8 Sep 2023 13:28:15 +0100 Subject: [PATCH 8/8] Update website/docs/docs/build/packages.md --- website/docs/docs/build/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/packages.md b/website/docs/docs/build/packages.md index 4d0bfd808a1..97e8784416e 100644 --- a/website/docs/docs/build/packages.md +++ b/website/docs/docs/build/packages.md @@ -301,7 +301,7 @@ Other patterns may work in some cases, but not always. For example, if you insta ```yaml packages: - # not recommended - the support for these patterns vary + # not recommended - support for these patterns vary - local: /../../redshift # relative path to a parent directory - local: /opt/dbt/redshift # absolute path on the system ```