Skip to content

Contributing guide

Table of contents

General

We welcome all contributions from the community. Adhere to Code of Conduct at all times.

Non-code contributions

We welcome non-code contributions as well. If you have any suggestions, ideas, or want to report a bug, follow these steps:

  1. Verify open issues ⧉ to see if someone reposrted similar issue or requested a similar feature.
  2. If the issue exists, upvote it and share more information in a comment (use cases, examples and so on).
  3. If the issue does not exist, create a new one from the Issues Templates ⧉ tab.
  4. Follow the appropriate template for the issue

Code contributions

Prerequisites

  1. Read ROADMAP to understand the project's goals.
  2. Read Developer's Certificate of Origin (DCO) in DCO.md (you must sign-off your PRs).
  3. Read LICENSE.
  4. Follow the steps in Non-code contributions and report a bug or request a feature.
  5. Fork the repository (see here ⧉ for more information).

Environment setup

Prerequisites (one time setup):

  1. Check you have Python 3.x installation available (as python3 or python)
  2. Install pdm (see official installation instructions ⧉)
  3. Enable pep582 globally (see official instructions ⧉)

Change to the cloned directory and run:

pdm setup

Caution

This project uses PEP582 ⧉ to manage dependencies. Check __pypackages__/README.md for more information.

Tip

Check here ⧉ for more information on IDE configuration with PEP582.

Source code

After the setup, you will, probably, contribute to the following directories:

Check project documentation ⧉ and code/docs in these folders for more information.

Making changes

Keep the following in mind:

  • Tests matter - use hypothesis (or similar) for property-based testing if possible.
  • Any changes need 100% test coverage - if not possible, explain why in the comments or PR description and exclude these lines).
  • Your changes should pass pre-commit hooks ⧉.

Note

Pre-commit hooks automatically fix your code, therefore you might have to recommit multiple time before the commit is accepted.

Committing changes

Please follow the simplified Conventional Commits ⧉ standard in every commit, for example:

git commit -s -S -m "feat: add new feature"
  • You can only use fix, feat, fix!, feat! types, we do not accept any other types (e.g. chore, refactor, docs and others).
  • Your commits should be atomic and should not contain many changes.
  • Your commits have to be signed-off (use -s flag in git commit as in the example above). Please see the DCO for more information.
  • Your commits have to be signed (use -S flag in git commit as in the example above). Please see the Signing commits ⧉ for more information.

Tip

You can use pdm commit-guided for interactive commit adhering to the guide.

Tip

You can use pdm commit (same as git commit -s -S).

Tip

You can use pdm commit-fast, a faster version of commit-guided.

Note

Signing and commit messages are automatically checked by the pre-commit hooks and CI/CD pipeline.

Creating a pull request

Follow GitHub Flow ⧉; main branch should always be in the releasable state.

Small pull requests are encouraged. If, for some reason, you cannot make small a pull request, describe the reasons in the pull request description.

Pull requests have to be:

  • Contain type akin to the commits; Same rules apply (only fix, feat, fix!, feat! allowed)
  • Linked to the issue via Closes #XXX (where XXX is the issue number) in the description.
  • Target the main branch.
  • Contain descriptive header and (optionally) description.

Tip

Type of the pull request should be the largest of all commits (feat! > fix! > feat > fix)

Other features:

  • Pull requests will be automatically labeled based on the type of the commit (in some cases, you might want to manually add the label from the existing ones).
  • Stale pull requests (no changes for 7 days) will be automatically closed (can be reopened later).
  • Pull requests will be automatically checked by the CI/CD pipeline.

Warning

Once you submit a PR, do not rebase it (easier to review the changes).

Merging pull requests

Maintainers will merge your pull request only after the CI/CD checks pass. In general, if pre-commit checks pass, no major changes should be necessary.

Note

We use Squash and Merge strategy for merging pull requests, individual commits should not matter if they follow the guidelines.

If you need help with this part of the process, tag one of the maintainers in the PR.

Coding style

pre-commit hooks check most of the guidelines, but maintainers reserve the right to ask for changes in the code style if necessary.

In special cases you might want to ignore a certain style rule, if so, describe the reason in the comment.

Releases

After maintainers merged your PR, your changes will be automatically included in the next release.

  • We release new versions of the project after each change according to the Semantic Versioning ⧉ specification.
  • CHANGELOG links to the release notes.
  • We show certain releases to the public by a blog post or a similar announcement (see ANNOUNCEMENTS).
  • Public releases comprise of a few merged pull requests and are performed under maintainers' discretion.