Skip to content

Latest commit

 

History

History
132 lines (88 loc) · 3.35 KB

CONTRIBUTING.rst

File metadata and controls

132 lines (88 loc) · 3.35 KB
Raw

Contributing

Everyone is invited to contribute to this project. Feel free to create a pull request . If you find errors, omissions, inconsistencies, or other things that need improvement, please create an issue.

Development Installation

Instead of pip-installing the latest release from PyPI, you should get the newest development version from Github:

git clone https://github.com/audeering/audbcards/
cd audbcards
# Create virtual environment for this project
# e.g.
# virtualenv --python="python3"  $HOME/.envs/audbcards
# source $HOME/.envs/audbcards/bin/activate
pip install -r requirements.txt

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

Coding Convention

We follow the PEP8 convention for Python code and use ruff as a linter and code formatter. In addition, we check for common spelling errors with codespell. Both tools and possible exceptions are defined in :file:`pyproject.toml`.

The checks are executed in the CI using pre-commit. You can enable those checks locally by executing:

pip install pre-commit  # consider system wide installation
pre-commit install
pre-commit run --all-files

Afterwards ruff and codespell are executed every time you create a commit.

You can also install ruff and codespell and call it directly:

pip install ruff codespell  # consider system wide installation
ruff check --fix .  # lint all Python files, and fix any fixable errors
ruff format .  # format code of all Python files
codespell

It can be restricted to specific folders:

ruff check audbcards/ tests/
codespell audbcards/ tests/

Building the Documentation

If you make changes to the documentation, you can re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:

pip install -r docs/requirements.txt

To create the HTML pages, use:

python -m sphinx docs/ build/html -b html

To ensure that anonymous access is used when communicating with Artifactory, you can call instead:

ARTIFACTORY_USERNAME=anonymous ARTIFACTORY_API_KEY="" python -m sphinx docs/ build/html -b html

The generated files will be available in the directory :file:`build/html/`.

It is also possible to automatically check if all links are still valid:

python -m sphinx docs/ build/html -b linkcheck

Running the Tests

You'll need pytest for that. It can be installed with:

pip install -r tests/requirements.txt

To execute the tests, simply run:

python -m pytest

Creating a New Release

New releases are made using the following steps:

  1. Update CHANGELOG.rst
  2. Commit those changes as "Release X.Y.Z"
  3. Create an (annotated) tag with git tag -a X.Y.Z
  4. Push the commit and the tag to Github