Contributing

March 20, 2026 · View on GitHub

Hi there! We're thrilled that you'd like to contribute to octoDNS. Your help is essential for keeping it great.

Please note that this project adheres to the Contributor Covenant Code of Conduct. By participating in this project you agree to abide by its terms.

If you have questions, or you'd like to check with us before embarking on a major development effort, please open an issue.

How to contribute

This project uses the GitHub Flow. That means that the main branch is stable and new development is done in feature branches. Feature branches are merged into the main branch via a Pull Request.

  1. Fork and clone the repository
  2. Configure and install the dependencies: ./script/bootstrap
  3. Activate virtual environment: source env/bin/activate
  4. Make sure the tests pass on your machine: ./script/test
  5. Create a new branch: git checkout -b my-branch-name
  6. Make your change, add tests, and make sure the tests still pass
  7. Make sure that ./script/lint passes without any warnings
  8. Run ./script/format to make sure your changes follow Python's preferred coding style
  9. Run ./script/changelog create ... to add a changelog entry to your PR
  10. Make sure that coverage is at :100:% ./script/coverage and open htmlcov/index.html
    • You can open a draft PR for :eyes: & discussion prior to this
  11. Push to your fork and submit a pull request

We will handle updating the version, tagging the release, and releasing the gem. Please don't bump the version or otherwise attempt to take on these administrative internal tasks as part of your pull request.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Write thorough tests. No PRs will be merged without :100:% code coverage. More than that tests should be very thorough and cover as many (edge) cases as possible. We're working with DNS here and bugs can have a major impact so we need to do as much as reasonably possible to ensure quality. While :100:% doesn't even begin to mean there are no bugs, getting there often requires close inspection & a relatively complete understanding of the code. More times than not the endeavor will uncover at least minor problems.

  • Bug fixes require specific tests covering the addressed behavior.

  • Write or update documentation. If you have added a feature or changed an existing one, please make appropriate changes to the docs. Doc-only PRs are always welcome.

  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.

  • We target Python 3, support for Python 2 has been dropped.

  • Write a good commit message.

Development setup

./script/bootstrap
source env/bin/activate

See the script/ if you'd like to run tests and coverage (script/coverage) and coverage (script/lint). After bootstrapping and sourcing the env/ commands in the octodns/cmds/ directory can be run with PYTHONPATH=. ./octodns/cmds/sync.py ...

Documentation and Read the Docs

Build docs locally

Use the docs helper script:

./script/generate-docs

By default this builds HTML into docs/_build/html/. You can choose another Sphinx builder with BUILDER, for example:

BUILDER=pdf ./script/generate-docs
BUILDER=epub ./script/generate-docs

The script runs sphinx-build --fail-on-warning, so any documentation warning fails the build.

How Read the Docs builds docs

Read the Docs configuration lives in .readthedocs.yaml:

  • Python 3.13
  • dependencies installed from requirements.txt
  • Sphinx configuration from docs/conf.py
  • extra formats: epub and pdf

During a Sphinx build, docs/conf.py rewrites repo-local links (e.g. /docs/..., /octodns/...) to full GitHub tree URLs. The ref used for those URLs is resolved in this order:

  1. OCTODNS_SOURCE_BASE_URL env var — explicit override (e.g. for forks, like https://github.com/MY_FORK/octodns )
  2. READTHEDOCS_GIT_IDENTIFIER — set automatically by Read the Docs
  3. Local git checkout context: branch → exact tag → short SHA
  4. Error - if no ref can be determined, the build fails with a clear message

This keeps generated source links aligned with the branch/tag/commit actually checked out for that docs build.

To build docs locally pointing to your fork:

OCTODNS_SOURCE_BASE_URL=https://github.com/MY_FORK/octodns \
./script/generate-docs

License note

We can only accept contributions that are compatible with the MIT license.

It's OK to depend on gems licensed under either Apache 2.0 or MIT, but we cannot add dependencies on any gems that are licensed under GPL.

Any contributions you make must be under the MIT license.

Resources