dbt-release
is a set of GitHub Reusable Workflows for automating releasing dbt-core
and adapter plugins.
- About this document
- Getting the code
- Setting up an environment
- Running in development
- Testing
- Debugging
- Adding or modifying a changelog entry
- Submitting a Pull Request
- Troubleshooting Tips
There are many ways to contribute to the ongoing development of dbt-release
, such as by participating in discussions and issues. We encourage you to first read our higher-level document: "Expectations for Open Source Contributors".
The rest of this document serves as a more granular guide for contributing code changes to dbt-release
(this repository). It is not intended as a guide for using dbt-release
, and some pieces assume a level of familiarity with GitHub workflow development. Specific code snippets in this guide assume you are using macOS or Linux and are comfortable with the command line.
- CLA: Please note that anyone contributing code to
dbt-release
must sign the Contributor License Agreement. If you are unable to sign the CLA, thedbt-release
maintainers will unfortunately be unable to merge any of your Pull Requests. We welcome you to participate in discussions, open issues, and comment on existing ones. - Branches: All pull requests from community contributors should target the
main
branch (default). - Releases: This repository is never released.
You will need git
in order to download and modify the source code.
If you are not a member of the dbt-labs
GitHub organization, you can contribute to dbt-release
by forking the dbt-release
repository. For a detailed overview on forking, check out the GitHub docs on forking. In short, you will need to:
- Fork the
dbt-release
repository - Clone your fork locally
- Check out a new branch for your proposed changes
- Push changes to your fork
- Open a pull request against
dbt-labs/dbt-release
from your forked repository
If you are a member of the dbt-labs
GitHub organization, you will have push access to the dbt-release
repo. Rather than forking dbt-release
to make your changes, just clone the repository, check out a new branch, and push directly to that branch.
There are some tools that will be helpful to you in developing locally. While this is the list relevant for dbt-release
development, many of these tools are used commonly across open-source python projects.
These are the tools used in dbt-release
development and testing:
flake8
for code lintingblack
for code formattingpre-commit
to easily run those checks
A deep understanding of these tools in not required to effectively contribute to dbt-release
, but we recommend checking out the attached documentation if you're interested in learning more about each one.
- Install pre-commit (docs)
- Use the following guidelines during development
- Each workflow should be self-documented
Workflows in this repository are all triggered with a workflow_call
so to test your changes you will need to set up a workflow in another repository to trigger your the modified workflow on your branch or fork. release.yml is what we use to trigger all the workflows in this repository and is a good example of how to trigger them.
There are no automated tests for this repository.
Workflows can be triggered with a test_run`` flag set to
true``. This publishes releases as Drafts in Github and also pushes release to pypi-test instead of production.
To use workflows inside other workflows, you can use the main
branch or specific commit SHA as a workflow tag.
Snippet:
build-test-package:
name: Build, Test, Package
if: ${{ !failure() && !cancelled() }}
needs: [bump-version-generate-changelog]
uses: dbt-labs/dbt-release/.github/workflows/build.yml@main
with:
sha: ${{ needs.bump-version-generate-changelog.outputs.final_sha }}
version_number: ${{ inputs.version_number }}
changelog_path: ${{ needs.bump-version-generate-changelog.outputs.changelog_path }}
build_script_path: ${{ inputs.build_script_path }}
s3_bucket_name: ${{ inputs.s3_bucket_name }}
package_test_command: ${{ inputs.package_test_command }}
test_run: ${{ inputs.test_run }}
nightly_release: ${{ inputs.nightly_release }}
secrets:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
Example: https://github.com/dbt-labs/dbt-core/blob/main/.github/workflows/release.yml
You can enable debug logging for GHA by setting secret values for your repository. See docs for more info.
- Set
ACTIONS_RUNNER_DEBUG
totrue
to enable runner diagnostic logging. - Set
ACTIONS_STEP_DEBUG
totrue
to enable run step debug logging.
- Sometimes flake8 complains about lines that are actually fine, in which case you can put a comment on the line such as: # noqa or # noqa: ANNN, where ANNN is the error code that flake8 issues.
Code can be merged into the current development branch main
by opening a pull request. A dbt-release
maintainer will review your PR. They may suggest code revision for style or clarity, or request that you add unit or integration test(s). These are good things! We believe that, with a little bit of help, anyone can contribute high-quality code.
Automated tests run via GitHub Actions. If you're a first-time contributor, all tests (including code checks and unit tests) will require a maintainer to approve. Changes in the dbt-release
repository trigger integration tests against Postgres. dbt Labs also provides CI environments in which to test changes to other adapters, triggered by PRs in those adapters' repositories, as well as periodic maintenance checks of each adapter in concert with the latest dbt-release
code changes.
Once all tests are passing and your PR has been approved, a dbt-release
maintainer will merge your changes into the active development branch. And that's it! Happy developing 🎉
- Sometimes, the content license agreement auto-check bot doesn't find a user's entry in its roster. If you need to force a rerun, add
@cla-bot check
in a comment on the pull request.