CONTRIBUTING.rst

Contributing

Contributions are always welcome and appreciated! Here are some ways you can contribute.

Issues

You can and should open an issue for any of the following reasons:

• you found a bug; steps for reproducing, or a pull request with a failing test case will be greatly appreciated
• you wanted to do something but did not find a way to do it after reading the documentation
• you believe the current way of doing something is more complicated or less elegant than it can be
• a related feature that you want is missing from the package

Please always check for existing issues before opening a new issue.

Pull requests

You want to contribute some code? Great! Here are a few steps to get you started:

1. Fork the repository on GitHub

2. Clone your fork and create a branch for the code you want to add

3. Create a new virtualenv and install the package in development mode

   $ python -m venv venv
   $ source venv/bin/activate
   (venv) $ python -m pip install -U pip setuptools
   (venv) $ pip install -U -e .[validation]
   (venv) $ pip install -U -r requirements/dev.txt

4. Make your changes and check them against the test project

   (venv) $ cd testproj
   (venv) $ python manage.py migrate
   (venv) $ python manage.py runserver
   (venv) $ firefox localhost:8000/swagger/

5. Update the tests if necessary

   You can find them in the tests directory.

   If your change modifies the expected schema output, you should regenerate the reference schema at tests/reference.yaml:

   (venv) $ python testproj/manage.py generate_swagger tests/reference.yaml --overwrite --user admin --url http://test.local:8002/

   After checking the git diff to verify that no unexpected changes appeared, you should commit the new reference.yaml together with your changes.

6. Run tests. The project is setup to use tox and pytest for testing

   # install test dependencies
   (venv) $ pip install -U -r requirements/test.txt
   # run tests in the current environment, faster than tox
   (venv) $ pytest -n auto --cov
   # (optional) sort imports with isort and check flake8 linting
   (venv) $ isort --apply
   (venv) $ flake8 src/drf_yasg testproj tests setup.py
   # (optional) run tests for other python versions in separate environments
   (venv) $ tox

7. Update documentation

   If the change modifies behaviour or adds new features, you should update the documentation and README.rst accordingly. Documentation is written in reStructuredText and built using Sphinx. You can find the sources in the docs directory.

   To build and check the docs, run

   (venv) $ tox -e docs

8. Push your branch and submit a pull request to the master branch on GitHub

   Incomplete/Work In Progress pull requests are encouraged, because they allow you to get feedback and help more easily.

9. Your code must pass all the required CI jobs before it is merged

   As of now, this consists of running on the supported Python, Django, DRF version matrix (see README), and building the docs succesfully.

Maintainer's notes

Release checklist

• update docs/changelog.rst with changes since the last tagged version
• commit & tag the release - git tag x.x.x -m "Release version x.x.x"
• push using git push --follow-tags
• verify that Actions has built the tag and successfully published the release to PyPI
• publish release notes on GitHub
• start the ReadTheDocs build if it has not already started
• deploy the live demo on Heroku