If you’re using a dbt package, and make improvements to it, we’d love for you to contribute that back to the dbt community.
This document runs through the workflow I would use to do this. I’m going to use a specific example here, but this workflow applies to all packages.
Let’s say you’re trying to use the
segment package in a project named
jaffle_shop, but have found that the package needs some work to make it compatible with my warehouse. You decide that you’re going to make the package work on your warehouse, and want to contribute that back to the wider dbt community.
0. Install the existing package in your dbt project
This is sort of a baked in assumption – since you want to use the Segment package, you’ve already installed it in your project, tried to use it, and then gotten some sort of error back, which is why you have decided to make changes to the package.
At the moment, your
packages.yml file (docs) looks like this:
# packages.yml packages: - package: fishtown-analytics/segment version: 0.2.3
1. Fork the dbt package you want to work on
To work on a dbt package, you need to have edit access to the repository. As an external contributor, this means that you need to fork Fishtown Analytics’ repository for the Segment package to my own GitHub account.
2. Clone the repository
Clone the repository into a directory, for example:
3. Install the local version of the package in my project
packages.yml file to point to the clone of the segment repository.
packages: - local: /Users/claire/clrcrl/packages/segment
Use whichever path you cloned your repo into! I also like to check out a new branch in my project, like
scratch/local-segment-package to make sure that I don’t commit the code.
dbt clean (to remove the published package) and
dbt deps (to install the local package) from the command line.
4. Make changes to the package
Make any changes to the repo, following a normal git flow (open a new branch, committing, etc.)
To test my changes, run your dbt project and see if the changes work! Often I have two terminal tabs open – one open for my project, and one for the package.
I also have both the package and my project open in my code editor (Atom):
Note that as you develop, you don’t need to re-run
dbt depsevery time you make updates to the Segment package – when using a
localpackage, dbt will always use the current files on my computer.
5. Test the changes
Some packages (e.g. dbt-utils and snowplow) have integration tests set up. If this is the case, add tests for your changes to ensure they work.
( This is sort of a vague statement because this really depends on the package you’re working on)
For most packages, testing of models really just involves ensuring the code runs, which you should do by running my project (as described above).
5. Open up a PR
Once you’ve made my changes, push the branch to GitHub, and open up a PR against the main repository! From here, one of the team members from Fishtown will review the PR, give feedback (if required), and merge it!