Development guide

This page provides procedures and guidelines for developing and contributing to Ook.

Scope of contributions

Ook is an open source package, meaning that you can contribute to Ook itself, or fork Squarebot for your own purposes.

Since Ook is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.

Ook is developed by the Rubin Observatory SQuaRE team.

Setting up a local development environment

Local development requires:

  • Python 3.13

  • Uv

  • Docker or a compatible container runtime

Ook is a Python project that should be developed within a virtual environment. You can create this virtual environment yourself, or use nox -s venv-init to create one for you.

If you already have a Python virtual environment set up in your shell, you can use the nox -s init command to install Ook and its development dependencies into it:

git clone https://github.com/lsst-sqre/ook.git
cd ook
uv run --group=nox nox -s init

This init step does two things:

  1. Installs Ook along with its runtime and development dependencies.

  2. Installs the pre-commit hooks.

Nox can create the virtual environment for you and install Ook and its development dependencies init it:

git clone https://github.com/lsst-sqre/ook.git
cd ook
uv run --group=nox nox -s venv-init
source .venv/bin/activate

This init step does three things:

  1. Creates a venv virtual environment in the .venv subdirectory.

  2. Installs Ook along with its runtime and development dependencies.

  3. Installs the pre-commit hooks.

Whenever you return to the project in a new shell you will need to activate the virtual environment:

source .venv/bin/activate

Pre-commit hooks

The pre-commit hooks ensure that files are valid and properly formatted. The hooks are automatically installed by running the nox -s init-dev or nox -s init commands on set up.

When these hooks fail, your Git commit will be aborted. To proceed, stage the new modifications and proceed with your Git commit.

Refer to the .pre-commit-config.yaml file for the list of hooks that are run.

Running tests

To test all components of Ook, run nox, which tests the library the same way that the GitHub Actions CI workflow does.

nox

uv run --group=nox nox

File linting, type checking, and unit tests are run as separate nox sessions:

nox -s lint
nox -s typing
nox -s unit

uv run --group=nox nox -s lint
uv run --group=nox nox -s typing
uv run --group=nox nox -s unit

With unit tests, you can run a specific test file or directory:

nox -s test -- tests/foo_test.py

uv run --group=nox nox -s test -- tests/foo_test.py

To see a listing of specific nox sessions, run:

nox --list

uv run --group=nox nox --list

Building documentation

Documentation is built with Sphinx:

nox -s docs

uv run --group=nox nox -s docs

The built documentation is located in the docs/_build/html directory.

To check the documentation for broken links, run:

nox -s docs-linkcheck

uv run --group=nox nox -s docs-linkcheck

Updating the change log

Ook uses scriv to maintain its change log.

When preparing a pull request, run

nox -s scriv-create

uv run --group=nox nox -s scriv-create

This will create a change log fragment in changelog.d. Edit that fragment, removing the sections that do not apply and adding entries for your pull request.

Change log entries use the following sections:

  • Backward-incompatible changes

  • New features

  • Bug fixes

  • Other changes (for minor, patch-level changes that are not bug fixes, such as logging formatting changes or updates to the documentation)

Do not include a change log entry solely for updating pinned dependencies, without any visible change to Ook’s behavior. Every release is implicitly assumed to update all pinned dependencies.

These entries will eventually be cut and pasted into the release description for the next release, so the Markdown for the change descriptions must be compatible with GitHub’s Markdown conventions for the release description. Specifically:

  • Each bullet point should be entirely on one line, even if it contains multiple sentences. This is an exception to the normal documentation convention of a newline after each sentence. Unfortunately, GitHub interprets those newlines as hard line breaks, so they would result in an ugly release description.

  • Avoid using too much complex markup, such as nested bullet lists, since the formatting in the GitHub release description may not be what you expect and manually editing it is tedious.

Style guide

Code

  • The code style follows PEP 8, though in practice lean on Black and ruff to format the code for you. Use SQR-072 for for architectural guidance.

  • Use PEP 484 type annotations. The nox -s typing test session, which runs mypy, ensures that the project’s types are consistent.

  • Write tests for Pytest.

Documentation