Ctrl+K

Contribution

Contribution#

Development#

Install this project, the required dependencies and the pre-commit hooks for development.

You have to clone this project first and run the following commands in the root folder of this project.

pip install -e ".[dev]"
pre-commit install

Build Documents#

Install the required dependencies to build the documents.

pip install -e ".[doc]"

Launch the live server to build and preview the documents.

sphinx-autobuild docs docs/_build

Build Package#

Install the required dependencies to build the package.

pip install -e ".[build]"

Build the package.

python -m build

Unit Tests#

Install the required dependencies to run unit tests.

pip install -e ".[test]"

Run the unit tests.#

pytest

Run the unit tests with coverage.#

pytest --cov=.

Run the unit tests with various python version.#

tox -- --cov=.

Code Style and Git Hooks#

The code is formatted and linted by ruff. The docstring is in Google style and formatted by docformatter. The spelling is checked by codespell. All commit messages should follow the conventional commit style to generate the changelog and semantic version automatically.

All the above requirements are checked by pre-commit hooks. You can install them by pre-commit install after you clone the repo.

Version, Tag and Release#

We use commitizen to bump the semantic version, create tags and generate the changelog automatically according to the commit messages. Then, setuptools_scm is used to generate the version number from the tags. Therefore, all commit messages should follow the conventional commit style to facilitate the version management tools.

Fortunately, the commitizen can be used to generate the commit messages in the conventional commit style. The whole process of contribution is as follows:

  • Install commitizen. You can install it by pip install commitizen, or if you have installed the [dev] extra dependencies, you can skip this step since commitizen has already been included in the [dev] extra dependencies. If you are using vscode, you can install the Commit Message Editor extension to generate the commit message following the conventional commit style.

  • Make changes.

  • Commit changes. Then you can use cz commit to commit your changes. It will guide you to write the commit message in the conventional commit style.

  • Bump version (Optional). If you have made some commits related to codes with feat, fix, refactor, perf or BREAKING CHANGE category, you can use cz bump to bump the version and generate the changelog automatically.

  • Push changes. Then you can push your changes to the remote repo. If you have bumped the version, you should push the tags to the remote repo by git push --tags. If you are using the vscode, you can set git.followTagsWhenSync to true to automatically push the tags when you run the sync command.

Contents