Skip to content

Latest commit

 

History

History
102 lines (66 loc) · 3.32 KB

CONTRIBUTING.rst

File metadata and controls

102 lines (66 loc) · 3.32 KB
Raw

Contributing

Contributions are welcome.

Local development

Dependencies

You need at least the following list of tools installed:

  • Python >= 3.8 (The library supports all Python versions >= 3.8, so all code needs to be backwards compatible with 3.8)
  • Poetry >= 1.3.0
  • Pre-Commit (optional)

Make sure that you install all dependencies, even the optional ones.

poetry install --all-extras --with docs

In a shell activate the virtual environment from poetry with poetry shell, and/or in an IDE set the path to the virtual environment which you can get via poetry env info.

Formatting / Linting

Code formatting is done with Black, linting with Ruff.

To get formatting/linting support in your IDE you might need to configure your IDE or install IDE extensions. However you can also run them in a shell with:

# check code style and fix potential issues
black .

# lint the code
ruff .
# lint and fix autofixable problems
ruff . --fix

Both tools can also be run automatically before each commit with Pre-Commit. You just need to activate Pre-Commit once.

pre-commit install

Testing / Static type checking

Testing is done via pytest, and static type checks are performed by Mypy.

Additionally you can use tox to run all checks and tests in multiple Python versions. tox will create new virtual environments for every Python version, make sure that Poetry and all the project's dependencies are installed in it, and then run the checks. However tox can only work with Python versions that it can find, so you need to install them (e.g. with pyenv).

# run tests
pytest

# run static type checker
mypy

# run everything with Python 3.8
# similar for 3.9, 3.10, 3.11 and 3.12
tox -e py38

# run everything in all supported Python versions
tox

Documentation

Documentation is built via Sphinx and published to Read The Docs.

# rebuild and live reload docs
sphinx-autobuild docs docs/_build/html

# alternatively build HTML docs the typical way
cd docs
make html

All code snippets in doctest directives are also tested when you run pytest.

Continuous Integration

All mentioned checks in the section above (formatting, linting, tests, static type checks) are also automatically run for every single Pull Request on Github.

Deployments

The library is versioned using Semantic Versioning. To release a new version, create a Github Release and specify a new version number (e.g. v1.7.2) as tag. Once the release is published, the new tag is created and a Github Action pipeline is triggered. The pipeline needs to be approved by a core developer, and afterwards the library is deployed to Pypi.