From f5fa01caa8cea9a398e6eeaf05743c900284450f Mon Sep 17 00:00:00 2001 From: PD Hall <20580126+pdhall99@users.noreply.github.com> Date: Tue, 15 Sep 2026 21:33:31 +0100 Subject: [PATCH] Broaden CONTRIBUTING.md --- docs/CONTRIBUTING.md | 89 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 72 insertions(+), 17 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9b32339..7ab4342 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,26 +1,71 @@ # Contributing -A lightweight span-annotation widget for interactive Python environments. - Thank you for considering making a contribution. +Contributions can include: + +- Reporting bugs +- Suggesting improvements or new features +- Improving documentation +- Adding or improving tests +- Making code changes + +## Raising issues + +Use GitHub issues to report bugs or suggest changes. + +Before raising an issue, search the existing open and closed issues to see whether it has already been reported or discussed. + +### Reporting bugs + +A useful bug report should include enough information for someone else to reproduce and investigate the problem. + +Where relevant, include: + +- A clear description of the problem +- The behaviour you expected +- The behaviour you observed +- A minimal example that reproduces the problem +- The version of the library you are using +- Your Python version +- Any relevant error messages or tracebacks + +Please use code blocks for code, output, and tracebacks. + +If possible, reduce examples to the smallest case that still demonstrates the problem. +This makes it easier to determine whether the behaviour is a bug and to identify its cause. + +### Suggesting changes + +Feature requests and other suggestions are also welcome. + +Describe the problem or use case you would like to address rather than only the proposed implementation. +Where useful, include: + +- The behaviour you would like +- Why it would be useful +- Examples of how it might be used +- Alternatives you have considered + +For substantial changes, please raise an issue before starting implementation, so that any decisions can be made before significant work is done. + ## Prerequisites +For code contributions you will need: + - A GitHub account - A development environment with: + - Python 3.10 (the minimum version of Python supported) - `hatch>=1.17` - Access to the internet for GitHub and installation of packages from PyPI -If `hatch` is not available in your development environment, install it by running - -```shell -uv tool install "hatch>=1.17" -``` +If Hatch is not available in your development environment, see the [Hatch installation instructions](https://hatch.pypa.io/latest/install/). ## Setup The project uses Hatch to manage Python environments for development. + To set up your development environment, run ```shell @@ -29,14 +74,21 @@ hatch run pre-commit:install ## Workflow -To make a code contribution: +To make a contribution: 1. Make a branch for your changes, either - - in the repo if you have write access, or - - in a fork of the repo if you do not have write access -2. Make and commit code changes on your branch until they meet the definition of done below + + - in the repo if you have write access, or + - in a fork of the repo if you do not have write access +2. Make and commit changes on your branch until they meet the definition of done below 3. Make a pull request from your branch to the main branch in the repo +Keep pull requests focused on a single change where practical. +Unrelated changes are easier to review when submitted separately. + +Documentation-only and other non-code contributions can use the same workflow. +Only the checks and definition-of-done items relevant to the change need to apply. + ### During development #### Testing @@ -51,34 +103,37 @@ hatch test --python 3.10 tests/test_foo.py # One file, one Python version ``` Use these commands for a fast iterative development loop. + Run the full `hatch test --all` matrix before opening a pull request. #### Adding dependencies -Add dependencies in `pyproject.toml` +Add dependencies in `pyproject.toml`. + The core package is intentionally dependency-free; a new runtime dependency requires a design-level justification. ### Checks -Making a pull request normally triggers CI checks, which must pass before the pull request can be merged into main. +Pull requests must pass checks in CI before they can be merged into main. -Run these same checks in your development environment and fix any problems before opening a pull request: +Run the same checks in your development environment and fix any problems before opening a pull request: ```shell hatch check code --fix # Check and fix linting and formatting using ruff - Note that this mutates files hatch check types # Check type annotations using pyrefly -hatch test --all # Run tests using pytest for all locally available versions of python in the matrix -hatch run docs:build # Build the Zensical documentation site +hatch test --all # Run tests using pytest for all locally available versions of Python in the matrix hatch run pre-commit:ci # Run all pre-commit hooks ``` Some of these commands modify files in your working tree: `hatch check code --fix` applies lint and formatting fixes, and other pre-commit hooks may also modify files. + After running the commands, review and commit the resulting changes — otherwise CI will run against the unfixed version and fail. + A clean run that leaves no changes means there was nothing to fix. ### Definition of done -Code changes are ready for review when +Changes are ready for review when all applicable items below are complete: - Relevant tests have been added or updated in the `tests/` directory - Relevant documentation has been added to or updated in the `docs/` directory