Simplify recommendations for using packages.yml and dependencies.yml

[dbeatty10]

Contributions

• I have read the contribution docs, and understand what's expected of me.

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

https://docs.getdbt.com/docs/collaborate/govern/project-dependencies#use-cases

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

db users have (4) choices as it relates to packages.yml and dependencies.yml files:

1. Neither packages.yml nor dependencies.yml
2. Only packages.yml
3. Only dependencies.yml
4. Both packages.yml and dependencies.yml*

* If both files exist, then only one of them can define the packages: key (i.e., packages.yml !).

To me, the most simple instructions would be:

1. Add any package dependencies to packages.yml
2. Add any project dependencies to dependencies.yml

That would keep things very understandable without needing to get into the details of caveats like Jinja, private packages, etc.

Additional information

See also: #6029

Relevant GitHub issues:

• [Regression] Jinja templating not working in dependencies.yml dbt-core#11109

[mirnawong1]

hey @dbeatty10 , this is a great issue! however, i believe we added additional caveat details like jinja, etc. because users raised this as a point of confusion and wanting to understand why jinja rendering isn't allowed in dependencies.yml (slack thread).

so based a couple of user thread/tickets i recall, it think it's best to keep the jinja,private packages caveats since they did come up multiple times before we added those caveats. so erring on the side of overcommunicating so users can self-answer any questions they have via the docs, rather than raise a ticket or question.

I'll close this issue for now, but let me know if you have any thoughts and i appreciate you opening this up!

[dbeatty10]

erring on the side of overcommunicating so users can self-answer any questions they have via the docs, rather than raise a ticket or question.

Very good points!

My main thought is that there's no special information needed if users just split their packages and mesh dependencies across two files: packages.yml and dependencies.yml.

But right now, a user would have to read the entire page to come to that conclusion. So I'm wondering if there's some way we could lead with the "short story" (just use two different files!)? And then provide the full details either in a separate page or further down on the same page.

Maybe something like this?

The most simple heuristic that will work for every dbt project is:

1. Add any package dependencies to packages.yml
2. Add any project dependencies to dependencies.yml

But many folks can consolidate both into a single dependencies.yml file. Read below to learn more.

[mirnawong1]

oh i see, yea that's a good idea! I've re-opened this, thanks for explaining @dbeatty10 !