Contributing Guidelines

Contributions are welcome through issues and pull requests. Start with the development setup.

Git hooks

Install the pre-commit hooks before your first commit:

pre-commit install

.pre-commit-config.yaml lists the hooks.

Code style

Follow PEP-8 and the existing code style. The pre-commit hooks run the tools:

• ruff lints and formats first.

• black formats the code.

• isort sorts the imports.

• flake8 checks for errors and style violations.

• Docstrings follow the Sphinx style.

Two habits the whole repository keeps: no em dashes, and two short sentences rather than one long sentence joined by a dash.

Before changing code

Three pages of the documentation record what the code cannot tell you. Read them first, in this order: architecture, invariants, conventions. A change that breaks an invariant is a bug even when every test passes.

Tests

Every fix comes with a test that fails without it. Run the new test against the old code once to prove that it does. See testing.

Documentation

Documentation is part of the change, not a follow-up. A pull request that changes what the user sees also updates the pages that describe it. That means the usage guide for anything in the dialog, and CHANGELOG.md under Unreleased for anything worth telling a user. The documentation page lists what to touch for each kind of change. It also says how to rebuild the screenshots, which a script generates.