Contributing to reporule¶

Reporting bugs¶

If something isn’t working as described, or if you find a mistake in the documentation, please feel free to report a bug by opening an issue.

Contributing to the code base¶

Contributions to the code base are welcome. If you want to add a new feature, please open an issue before doing any work, to ensure that the suggestion aligns with the project’s goals and overall direction.

If you’d like to tackle an existing issue, please leave a comment on it.

Creating your local development environment¶

For contributing to this code base, you’ll need:

A GitHub account
Git installed on your machine
optional: uv (the Python-based directions below use uv, but if you already have a preferred Python toolset, that should work too)

[!IMPORTANT] If you have an active Python virtual environment (for example, conda’s base environment), you’ll need to deactivate it before following the instructions below.

Configure git¶

On GitHub, fork this repository.

Clone the forked repository to your machine:

git clone https://github.com/<your github username>/<this-repo-name>.git
cd <this-repo-name>

optional: Set the upstream remote to sync your fork with this repository:

git remote add upstream https://github.com/<this-repo-owner-or-org-name>/<this-repo-name>.git
git fetch upstream

Install project and dependencies¶

From the root of the repo, create a virtual environment and install the project dependencies. The uv sync command handles installing Python, creating a virtual environment, and installing project dependencies.
```
uv sync
```
(More information about how uv finds or downloads a Python interpreter)
Run the test suite to check that everything works correctly:

[!TIP] Prefixing python commands with uv run instructs uv to run the command in the project’s virtual environment, even if you haven’t explicitly activated it.
```
uv run pytest
```
Install the pre-commit hooks used for linting and other checks (this may take a few minutes but only needs to be done once).
```
uv run pre-commit install
```
Make sure the pre-commit checks are working correctly:
```
uv run pre-commit install
```

Updating your development environment¶

If time has passed between your initial project setup and when you make changes to the code, make sure your fork and development environment are up-to-date.

Sync your fork to the upstream repository:

git checkout main
git fetch upstream
git rebase upstream/main
git push origin main

Update your project dependencies:
```
uv sync
```

Adding project dependencies¶

If your change requires a new dependency, add it as follows:

uv add <dependency>

The uv add command will:

Add the dependency to pyproject.toml
Install the dependency into the project’s virtual environment
Update the project’s lockfile (uv.lock)

Make sure to commit the updated versions of pyproject.toml and uv.lock.

Updating documentation¶

This project uses Sphinx and MyST-flavored markdown for documentation.

Documentation updates should be made in docs/source. To preview changes:

uv run --group docs sphinx-autobuild docs/source docs/_build/html

The output of the above command provides a URL for viewing the documentation via a local server (usually http://127.0.0.1:8000).

Submitting code changes¶

After you’ve completed the changes described in the issue you’re working on, you can submit them by creating a pull request (PR) to this repository.

Please ensure the following are true before creating the PR:

Your change is covered by tests, if applicable
Project documentation is updated, if applicable
All tests pass (uv run pytest)
All pre-commit checks are successful (these checks will run automatically as you make commits)
The [Unreleased] section of CHANGELOG.md contains a description of your change.

The PR itself should:

Have a descriptive title
Be linked to its corresponding issue in the description.
Have a description that includes any other information or context that will help a code reviewer understand your changes.