Contributing to drf-spectacular

As an open source project, drf-spectacular welcomes any form of contribution. The project was initially forked off DRF’s schema generator and has since then been continually receiving improvements from the community. Your contribution matters even if it is only a small one.

Contributions come in different shapes and sizes.

  • Documentation improvements, clarifications & fixing typos

  • Creating issues for feature requests & bug reports

  • Creating pull requests for features and bug fixes

  • Questions that highlight inconsistencies or workflow issues

  • Adding blueprints for not officially supported 3rd party tools.

Issues

Generating schemas is a complicated business and the devil often lies in the details. A concise description with examples goes a long way towards getting a good understanding of the issue at hand. If possible/applicable please include

  • A concise description

  • Example code that produces the issue

  • Generated (partial) schema with the issue

  • Stacktraces if an error occurred

  • drf-spectacular/Django/DRF versions

Pull requests

drf-spectacular prides itself on having very high code coverage and an extensive test suite. It is really well tested, which enables us to maintain quality, reliability, and consistency.

  • The git history is important to the project. Please make minimally invasive changes where possible. On receiving feedback, we prefer having a small set of amended commits. Consider using git commit --amend and git push --force for updating your PR.

  • If you have a non-trivial PR please consider getting early feedback. We don’t want to waste anyone’s time.

  • We have great tooling around tests. Have a look into test_regressions.py for inspiration. The tests are mainly structured in feature units but in doubt small things go into the regressions.

  • We use tox to make sure drf-spectacular works for a range of Django/DRF versions. Your PR must pass the whole test suite to get merged. Local testing with ./runtests.py usually suffices. You don’t need to install a bunch of python versions. The github actions for PRs will take care of the rest.

A quick cheat sheet to get you rolling

$ # fork the repo on github
$ git clone https://github.com/YOURGITHUBNAME/drf-spectacular
$ cd drf-spectacular
$ python -m venv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt
(venv) $ ./runtests.py  # runs tests (pytest) & linting (isort, flake8, mypy)

With that out of the way, we hope to hear from you soon.