Clarify predictable package installs and git packages

[mirnawong1]

Contributions

• 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:

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 -- "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 -- "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

[christineberger]

I also had a related issue last week where a user was confused about what needed to happen - they added package-lock.yml to the .gitignore and while the docs state

An alternative to running dbt deps --upgrade in production is to "ignore" the lock file by adding package-lock.yml to your project's .gitignore file.

they were unaware of how the .gitignore is different from dbt functionality and interpreted this as "if you add the file to .gitignore, then dbt won't lock packages to a package-lock.yml file". Once clarifying, they wanted more direction from a development perspective in the docs: in development, users will still have a package-lock.yml and if you are installing from a private package pointed to main, then there will not be any changes seen from the packages/dependencies.yml for that package if package-lock.yml has already been created once, thus leading to the package not being updated unless dbt deps --upgrade is run (which we do mention, but it doesn't seem detailed enough for a user to fully understand when they will need to use it)