Contributing to an external dbt package

Archive
1

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: /Users/claire/clrcrl/packages/segment

3. Install the local version of the package in my project

Update the packages.yml file to point to the clone of the segment repository.
For example:

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.

Then run 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.

53%20PM
53%20PM1784×1430 216 KB

I also have both the package and my project open in my code editor (Atom):
52%20PM
52%20PM2064×1574 563 KB

Note that as you develop, you don’t need to re-run dbt deps every time you make updates to the Segment package – when using a local package, 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.
(:point_up: 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!

6 Likes