How to edit the Handbook

Git Pre-commit Hooks

Git hooks let you automatically run scripts at various points as you manage your source code. “Pre-commit” hook scripts are run when you try to make a new commit. These scripts can review your code and identify bugs, formatting errors, bad coding habits, and other issues before the code gets checked in. This gives you the opportunity to fix those issues before publishing them.

To make sure they are run before you commit any code, you need to enable the pre-commit hooks scripts with this command:

pre-commit install

The scripts that run are configured in the .pre-commit-config.yaml file.

How to make changes

CLI

To make changes to the handbook, edit the relevant markdown documents in the docs/ directory. Once the changes are made you can build the docs by running:

uv run hatch run docs-build

This command will build the docs and write the html files to docs/_build/. You can view the docs locally by opening the docs/_build/index.html file. Once the docs are built locally, you can push your changes and open a PR for review. There is a GitHub Action that will build and deploy the changes to Read the Docs.

UI

If you don’t want to make edits with a CLI and code editor, you can use the GitHub UI:

1. Click the “Edit” button for the document you want to change:

2. Make your changes.

3. Select “Create a new branch for this comment and start a pull request”, add a commit message and select “Commit changes”:

4. Tag someone to review your changes.

The changes must be reviewed and approved by someone else to be merged into the main branch.

Updating COLA numbers

Each year we try to update our compensation to keep up with inflation. When the board decides to change our compensation we need to update the numbers in this handbook. To do this, update the values in the myst_substitutions dictionary in docs/conf.py. Check out this page to learn more about MyST substitutions.