Development guide#

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

Scope of contributions#

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

Since mobu 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.

mobu is developed by the Rubin Observatory SQuaRE team.

Setting up a local development environment#

Prerequisites#

mobu uses uv for all dependency management. A reasonably recent version of uv must already be installed. See the uv installation instructions if needed.

Set up development environment#

To develop mobu, create a virtual environment with uv venv and then run make init.

git clone https://github.com/lsst-sqre/mobu.git
cd mobu
make init

This init step does three things:

  1. Creates a Python virtual environment in the .venv subdirectory with the packages needed to do mobu development installed.

  2. Installs mobu in an editable mode in that virtual environment.

  3. Installs the pre-commit hooks (run by prek).

You can activate the mobu virtual environment if you wish with:

source .venv/bin/activate

This is optional; you do not have to activate the virtual environment to do development. However, if you do, you can omit uv run from the start of all commands described below. Also, editors with Python integration, such as VSCode, may work more smoothly if you activate the virtualenv before starting them.

Pre-commit hooks#

The pre-commit hooks, which are automatically installed by running the make init command on set up, ensure that files are valid and properly formatted. Some pre-commit hooks may automatically reformat code or update files:

blacken-docs

Automatically formats Python code in reStructuredText documentation and docstrings.

ruff

Lint Python code and attempt to automatically fix some problems.

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

If you have to commit changes that fail pre-commit checks, pass the --no-verify flag to git commit. This will have to be temporary, though, since the change will fail GitHub CI checks.

Despite the name, mobu uses prek to run pre-commit hooks rather than the package named pre-commit.

Running tests#

mobu uses nox as its automation tool for testing.

To run all mobu tests, run:

uv run nox

This will run several nox sessions to lint and type-check the code, run the test suite, and build the documentation.

To list the available sessions, run:

uv run nox --list

To run a specific test or list of tests, you can add test file names (and any other pytest options) after -- when executing the test nox session. For example:

uv run nox -s test -- tests/example_test.py

mobu uses the Safir test data library to manage test data. You can run a specific test function by appending two colons and the function name to the end of the file name.

If you change the code in a way that would change test output, run:

uv run nox -s test -- --update-test-data

This will update any test output files to match the current output of the test suite. Review any changes with git diff and ensure they match the expected changes.

Updating dependencies#

All mobu dependencies are configured in pyproject.toml like a regular Python package. Runtime dependencies are configured in project.dependencies, and development dependencies are configured under dependency-groups. The following dependency groups are used:

dev

Dependencies required to run the test suite, not including the dependencies required to run nox itself.

docs

Dependencies required to build the documentation.

lint

Dependencies required to run prek and to lint the code base.

nox

Dependencies required to run nox.

typing

Dependencies required to run mypy

These dependency groups are used by nox to install the appropriate dependencies based on the nox session. The development virtualenv in .venv will have all of these dependency groups installed so the developer can freely use commands such as ruff and mypy.

A frozen version of all of these dependencies is managed by uv in the file uv.lock. This is used to pin all dependencies so that they only change when a developer intends to update them and is prepared to run tests to ensure nothing broke.

After changing any dependency, run make update-deps to rebuild the uv.lock file. To also update the development virtualenv, run make update instead.

Temporary Git dependencies#

By default, all Python dependencies are retrieved from PyPI.

Sometimes during development it may be useful to test mobu against an unreleased version of one of its dependencies. uv supports this by setting a dependency source.

For example, to use the current main branch of Safir instead of the latest released version, add the following to the end of pyproject.toml:

[tool.uv.sources]
safir = { git = "https://github.com/lsst-sqre/safir", branch = "main", subdirectory = "safir" }

The uv add command can be used to configure these sources if desired. As always, after changing dependencies, run make update or make update-deps. mobu will now use the unreleased version of Safir.

Do not release new non-alpha versions of mobu with these types of Git dependencies. The other package should be released first before a new version of mobu is released.

Building documentation#

Documentation is built with Sphinx:

uv run nox -s docs

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

Additional dependencies required for the documentation build should be added to the docs dependency group in pyproject.toml.

Documentation builds are incremental, and generate and use cached descriptions of the internal Python APIs. If you see errors in building the Python API documentation or have problems with changes to the documentation (particularly diagrams) not showing up, try a clean documentation build with:

uv run nox -s docs-clean

This will be slower, but it will ensure that the documentation build doesn’t rely on any cached data.

To check the documentation for broken links, run:

uv run nox -s docs-linkcheck

Updating the change log#

mobu uses scriv to maintain its change log.

When preparing a pull request, run uv run 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 fo this pull request. You can pass the --edit flag to uv run scriv create to open the created fragment automatically in an editor.

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)

The change log entries should be written in imperative tense and describe to the user the change in behavior or the impact on the user at a high level. Changes that are not visible to the user, including minor documentation changes, should not have a change log fragment. Technical descriptions of how the change was implemented belong in commit messages, not change log entries.

Versioning assumes that mobu is installed via Phalanx, so changes to its internal configuration file do not count as backward-incompatible chnages unless they require changes to per-environment Helm values-environment.yaml files.

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

Formatting change log entries#

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.

  • Be cautious with complex markup, such as nested bullet lists, since the formatting in the GitHub release description may not be what you expect and manually repairing it is tedious.

Style guide#

Code#

  • mobu follows the SQR-072 Python style guide.

  • The code formatting follows PEP 8, though in practice lean on Ruff to format the code for you.

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

  • mobu uses the Ruff linter with most checks enabled. Its primary configuration is in ruff-shared.toml, which should be an exact copy of the version from the FastAPI Safir app template. Try to avoid noqa markers except for issues that need to be fixed in the future. Tests that generate false positives should normally be disabled, but if the lint error can be avoided with minor rewriting that doesn’t make the code harder to read, prefer the rewriting.

  • Write tests for pytest.

Documentation#

This page was last modified on .