Skip to content

Latest commit

 

History

History
88 lines (56 loc) · 4.57 KB

contribution.md

File metadata and controls

88 lines (56 loc) · 4.57 KB
Raw

Contribution

Development

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

We recommend you install all required dependencies including the development and project dependencies by pip install -e ".[all]". However, if you want to install only the necessary part of the dependencies, you can install the project and core development dependencies by pip install -e ".[deps,dev-core]" and install the required dependencies of each development action following the description in the following sections.

After you installed the project and the required dependencies, you can install the pre-commit hooks by pre-commit install.

Overall, we recommend you install all required dependencies and the pre-commit hooks by the following commands:

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

Build Documents

You have to install the required dependencies to build the documents, if you install the core development dependencies only in the previous section.

pip install -e ".[dev-doc]"

Launch the live server to build and preview the documents.

sphinx-autobuild docs docs/_build

Build Package

You have to install the required dependencies to build the package, if you install the core development dependencies only in the previous section.

pip install -e ".[dev-build]"

Build the package.

python -m build

Unit Tests

You have to install the required dependencies to run unit tests, if you install the core development dependencies only in the previous section.

pip install -e ".[dev-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.