dbt-labs / dbt-labs/docs.getdbt.com

Clarify predictable package installs and git packages

Open
#4,981 1 comment 0 reactions 0 assignees View on GitHub
content improvement
Dominant language
JavaScript
Stars
215
Forks
1.2k
Avg merge
1d 15h
Merged PRs (30d)
130

Description

### Contributions

- [X] I have read the contribution docs, and understand what's expected of me.

### Link to the page on docs.getdbt.com requiring updates

This was raised by our mighty support team in [slack](https://dbt-labs.slack.com/archives/C02NCQ9483C/p1708658516909119):

From Kyle:
Something in our docs led to a bit of confusion with a customer, and I wanted to ask for clarification.

- [About dbt deps command - Predictable package installs](https://docs.getdbt.com/reference/commands/deps#predictable-package-installs) -- "dbt generates a package-lock.yml file in the root of your project. This contains the complete set of resolved packages based on the packages configuration in dependencies.yml or packages.yml. Each subsequent invocation of dbt deps will install from the locked set of packages specified in this file"
- This seems to imply that if you pin to master, the package-lock.yml file will store the latest commit hash and will not automatically incorporate updates to package in subsequent dbt deps.

- [Packages - Git packages](https://docs.getdbt.com/docs/build/packages#git-packages) -- "If you use master, then any updates to the package will be incorporated into your project the next time you run dbt deps"
- This does not mention the package-lock.yml and implies that pinning a package to master will always pull the most recent updates to the package.

My understanding is that the "Predictable Package Installs" doc is accurate, and the omission of the package-lock.yml file concept in the "Git Packages" doc is not technically wrong but is a bit confusing.

### What part(s) of the page would you like to see updated?

From reading it, it sounds like they’re diff mechanisms to managed packages and leaves it up to the user to decide whether they want stability or flexibility. it sounds like the packages page should explicitly mention how this interacts with package-lock.yml

both pages would benefit from mentioning their relation to each other:

https://docs.getdbt.com/docs/build/packages#git-packages
https://docs.getdbt.com/reference/commands/deps#predictable-package-installs

We should also update the language to replace `master` to `main`.

### Additional information

_No response_

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.