CONTRIBUTING.md

Contributing to this repo

Table of contents

• Overview
• Running locally
  • Using Docker
• Use with dbt deps from dbt Core
• Managing the Gemfile and Gemfile.lock
  • Steps

Overview

There are two components to the dbt Hub:

• hub.getdbt.com: Our package registry
  • https://github.com/dbt-labs/hub.getdbt.com (this repo!)
  • An indexed collection of JSON files
  • A static site, served by those same JSON files, where users can discover available packages
  • Hosted on Netlify
• Hubcap: The way the Hub stays up to date!
  • https://github.com/dbt-labs/hubcap
  • A script that:
    • Catches new package releases when they are available (via GitHub releases)
    • Parses out metadata—crucially, this package's dependencies on other Hub packages
    • Records each release in a predictable format (JSON file)
    • Automatically opens a PR against hub.getdbt.com to add that JSON file to its indexed collection
  • Hosted on Heroku

Running locally

See local-ruby-environment.md for non-Docker instructions.

Using Docker

docker-compose build
docker-compose up -d

Either of the following should launch the website in your default web browser:

• http://127.0.0.1:4567
• http://localhost:4567

When finished:

docker-compose down

Use with dbt deps from dbt Core

Note: Make sure to remember to unset any environment variables that you set once you are done! unset YOUR_VARIABLE_NAME_HERE should work in bash/zsh. direnv is one option for loading/unloading environment variables automatically when entering/exiting a directory.

You can set the DBT_PACKAGE_HUB_URL environment variable to specify where dbt deps should look to resolve dependencies listed in packages.yml:

export DBT_PACKAGE_HUB_URL=http://localhost:4567/

Or if you have a Netlify preview created by a pull request:

export DBT_PACKAGE_HUB_URL=https://deploy-preview-1717--hub-getdbt-com.netlify.app/

Suppose your packages.yml in your dbt project contains the following content:

packages:
  - package: tnalpgge/cowsay
    version: 0.3.4

Then dbt deps will use the JSON served from the following locations:

• data/packages/tnalpgge/cowsay/index.json
• data/packages/tnalpgge/cowsay/versions/0.3.4.json

Managing the Gemfile and Gemfile.lock

Bundler manages gems used in a Ruby application. A file named Gemfile in your project root will contain gem names and optional version ranges.

Modifying the version of a Gem used is a two-step process. Modify the reference to a gem in the Gemfile and run a bundle update.

Steps

If using Docker, start an interactive shell on the running container first:

docker exec -it dbt-hub sh

And exit when finished performing the bundle update outlined below.

1. Add or modify a gem entry in Gemfile with the following syntax:
   • gem '<gem name>', '<version range>'
2. Update Gemfile.lock with:
   • bundle update <gem name needing update> or just bundle update
   • Running a bare bundle update may update multiple gems
   • Either way, testing will be needed to verify the application still works as intended afterwards
3. Commit Gemfile and Gemfile.lock changes in both to the repo