Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Code of Conduct

Everyone interacting in the Docs Versions Menu project’s code base, issue tracker, and any communication channels is expected to follow the PyPA Code of Conduct.

Report Bugs

Report bugs at https://github.com/goerz/docs_versions_menu/issues.

If you are reporting a bug, please include:

  • A link to a CI build log using docs-versions-menu --debug; or

  • A pull request with a failing test that illustrates the bug; or

  • Detailed steps to reproduce the bug.

  • All error messages in full, as plain text. If the output is long, attach it as a file.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/goerz/docs_versions_menu/issues.

If you are proposing a feature:

  • Explain in detail how it would work.

  • Keep the scope as narrow as possible, to make it easier to implement.

  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Development Guidelines

Prerequisites

Contributing to the package’s developments requires that you have Python 3.8 and tox installed. It is strongly recommended that you also have installations of all other supported Python versions. The recommended way to install multiple versions of Python at the same time is through pyenv (or pyenv-win on Windows).

Pull Requests

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.

  2. If the pull request adds functionality, the docs should be updated.

  3. Check https://github.com/goerz/docs_versions_menu/actions?query=workflow%3ATests and make sure that the tests pass for all supported Python versions.

Get Started!

Ready to contribute? Follow Aaron Meurer’s Git Workflow Notes (with goerz/docs_versions_menu instead of sympy/sympy)

In short,

  1. Clone the repository from git@github.com:goerz/docs_versions_menu.git

  2. Fork the repo on GitHub to your personal account.

  3. Add your fork as a remote.

  4. Pull in the latest changes from the master branch.

  5. Create a topic branch.

  6. Make your changes and commit them (testing locally).

  7. Push changes to the topic branch on your remote.

  8. Make a pull request against the base master branch through the Github website of your fork.

The project uses tox for automated testing accross multiple versions of Python and for various development tasks such as linting and generating the documentation. See Prerequisites for details.

There is also a Makefile that wraps around tox, for convenience on Unix-based systems. In your checked-out clone, run

make help

to see the available make targets. If you cannot use make, but want to use tox directly (e.g., on Windows), run

tox -av

to see a list of tox environments and a description.

Branching Model

For developers with direct access to the repository, Docs Versions Menu uses a simple branching model where all developments happens directly on the master branch. Releases are tags on master. All commits on master should pass all tests and be well-documented. This is so that git bisect can be effective. For any non-trivial issue, it is recommended to create a topic branch, instead of working on master. There are no restrictions on commits on topic branches, they do not need to contain complete documentation, pass any tests, or even be able to run.

To create a topic-branch named issue1:

git branch issue1
git checkout issue1

You can then make commits, and push them to Github to trigger Continuous Integration testing:

git push -u origin issue1

Commit early and often! At the same time, try to keep your topic branch as clean and organized as possible. You can use amend/rebase and force-push.

Testing

Docs Versions Menu includes a full test-suite using pytest. We strive for a test coverage above 90%.

From a checkout of the docs_versions_menu repository you can use

make test

to run the entire test suite, or

tox -e py36-test,py37-test,py38-test,py39-test

if make is not available.

The tests are organized in the tests subfolder. It includes python scripts whose name start with test_, which contain functions whose names also start with test_. Any such functions in any such files are picked up by pytest for testing. In addition, doctests from any docstring or any documentation file (*.rst) are picked up (by the pytest doctest plugin).

Code Style

All code must be compatible with PEP 8. The line length limit is 79 characters, although exceptions are permissible if this improves readability significantly.

Beyond PEP 8, this project adopts the Black code style, with --skip-string-normalization --line-length 79. You can run make black-check or tox -e run-blackcheck to check adherence to the code style, and make black or tox -e run-black to apply it.

Imports within python modules must be sorted according to the isort configuration in setup.cfg. The command make isort-check or tox -e run-isortcheck checks whether all imports are sorted correctly, and make isort or tox -e run-isort modifies all Python modules in-place with the proper sorting.

The code style is enforced as part of the test suite, as well as through git pre-commit hooks that prevent committing code not does not meet the requirements. These hooks are managed through the pre-commit framework.

You may use make flake8-check or tox -e run-flake8 and make pylint-check or tox -e run-pylint for additional checks on the code with flake8 and pylint, but there is no strict requirement for a perfect score with either one of these linters. They only serve as a guideline for code that might be improved.

Documentation

Docs Versions Menu could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.

The package documentation is generated with Sphinx, the documentation (and docstrings) are formatted using the Restructured Text markup language (file extension rst). See also the Matplotlib Sphinx cheat sheet for some helpful tips.

Each function or class must have a docstring; this docstring must be written in the “Google Style” format (as implemented by Sphinx’ napoleon extension).

At any point, from a checkout of the docs_versions_menu repository, you may run

make docs

or

tox -e docs

to generate the documentation locally.

Versioning

Releases should follow Semantic Versioning, and version numbers published to PyPI must be compatible with PEP 440.

In short, versions number follow the pattern major.minor.patch, e.g. 0.1.0 for the first release, and 1.0.0 for the first stable release. If necessary, pre-release versions might be published as e.g:

1.0.0-dev1  # developer's preview 1 for release 1.0.0
1.0.0-rc1   # release candidate 1 for 1.0.0

Between releases, __version__ on the master branch should either be the version number of the last release, with “+dev” appended (as a “local version identifier”), or the version number of the next planned release, with “-dev” appended (“pre-release identifier” with extra dash). The version string “1.0.0-dev1+dev” is a valid value after the “1.0.0-dev1” pre-release. The “+dev” suffix must never be included in a release to PyPI.

Note that twine applies normalization to the above recommended forms to make them strictly compatible with PEP 440, before uploading to PyPI. Users installing the package through pip may use the original version specification as well as the normalized one (or any other variation that normalizes to the same result).

When making a release via

make release

the above versioning conventions will be taken into account automatically.

Releases must be tagged in git, using the version string prefixed by “v”, e.g. v1.0.0-dev1 and v1.0.0. This makes them available at https://github.com/goerz/docs_versions_menu/releases.