Skip to content

Contributing

The guide is modified from mkdocstrings

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

Environment setup

First, fork and clone the repository, then cd to the directory.

We use hatch and pre-commit to manage our project.

You can install them with:

# https://pypa.github.io/pipx/
python3 -m pip install --user pipx

pipx install hatch
pipx install pre-commit

Then, initialize the env with:

# Init pre-commit
# https://pre-commit.com/#3-install-the-git-hook-scripts
pre-commit install
pre-commit run --all-files

# https://hatch.pypa.io/latest/environment/
hatch shell

That's all! Now, you can start to develop.

Code style

The source code is in src/

We use Ruff, Blcak, Pyright and Codespell to check our code style and lint.

Please check pyproject.toml to know our style.

If you want to format or lint-fix your code, you can use the following command:

hatch run lint

or, with pre-commit:

pre-commit run -a

or, dry run:

hatch run lint-check

Tip

If you use VSCode, we strongly recommend you to install the extensions in .vscode/extensions.json.
Because our code style rules are quite strict.
These extensions can help you know where need to be fixed when coding.

Testing

We use pytest to test our code.

The test source code is in tests/

You can run the testing with:

hatch run test

Documentation

We use mkdocs, mkdocs-material, mkdocstrings to build our documentation.

The documentation source code is in docs/, mkdocs.yml, may be there is also some source code in scripts/ or somewhere (check mkdocs.yml to find that).

Live-reloading docs:

hatch run docs:mkdocs serve

Build docs:

hatch run docs:docs-build

PR

  • PRs should target the main branch.
  • Keep branches up to date by rebase before merging.
  • Do not add multiple unrelated things in same PR.
  • Do not submit PRs where you just take existing lines and reformat them without changing what they do.
  • Do not change other parts of the code that are not yours for formatting reasons.
  • Do not use your clone's main branch to make a PR - create a branch and PR that.

Edit CHANGELOG.md

If you have made the corresponding changes, please record them in CHANGELOG.md.

Commit message convention

Commit messages must follow Conventional Commits, or, pre-commit may be reject your commit.

Info

If you don't know how to finish these, it's okay, feel free to initiate a PR, I will help you continue.

More

There may still be some useful commands in pyproject.toml, you can refer to hatch/environment/scripts to use them.

Info

If you find that the commands given in the above examples are incorrect, please open an issue, we greatly appreciate it.

😢

Warning

The following 👇 content is for the maintainers of this project, may be you don't need to read it.

deploy-docs

please refer to .github/workflows/docs.yml

CI: lint-test

please refer to .github/workflows/lint-test.yml

CI: pre-commit-ci auto-update

Every Monday, pre-commit-ci will send a PR for automatic hook version updates, which will trigger a local ver_sync hook.

The ver_sync hook will maintain lint tools version consistency between .pre-commit-config.yaml and pyproject.toml.

Please check whether the ver_sync works properly, then you can accept the PR.

Publish and Release 🚀

First, check-out to a new branch, edit CHANGELOG.md to record the changes.

Then, please refer to:

Update version in new branch with:

git add .
hatch version {new_version}

It will create a commit and tag automatically.

Then, push the new branch with tag to GitHub, and create a PR to main branch.

Warning

The bump version PR must have only one commit with the corresponding tag; otherwise, it will be rejected.

Review the PR, if it's ok, rebase it to main branch in local

Warning

DO NOT rebase with tag in GitHub, refer to https://docs.github.com/zh/authentication/managing-commit-signature-verification/about-commit-signature-verification#signature-verification-for-rebase-and-merge

Check if everything is ok, for example:

  • check if the tag is on the main branch.
  • check if the link in CHANGELOG.md is correct.

If so, make a approve in environment pypi for the workflow.

After that, the publish.yml workflow will build and publish the package to PyPI.

Finally, edit the draft release created by publish.yml workflow, and publish the release.

Warning

The creating of tag needs signature verification,
please refer to https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification