Workflows

This page covers how development actually flows through GitHub: how issues, branches and pull requests fit together, and what the automated checks on a pull request do (and which of them can block a merge). For how a new OpenAirClim version actually gets released, see Releasing. For the full contribution policy - code of conduct, commit message conventions, do’s and don’ts - see CONTRIBUTING.md.

Working with GitHub

Issues. Before starting work, open a GitHub issue to discuss what you are planning to do, using the bug report or feature request template. This applies even if you already know how you would implement it. Doing it this way gives the Steering Committee and other contributors a chance to weigh in before any code is written.

Branches. main and dev are protected and can only be changed via pull requests. New OpenAirClim versions are released from main. Everyday development happens on unprotected branches, named by what they contain: feature/<name>, bug/<name>, task/<name> and docs/<name>.

Contributors with write access to the repository (the core development team, or external collaborators the Steering Committee has approved) can create these branches directly. Everyone else works from a fork instead.

Pull requests. Reference the issue you opened (Closes #123) and fill out the pull request template - type of change, how it was tested, and the checklist (including confirming that example/example.toml still runs against a clean installation). Also apply a type label (type: feature, type: bug/type: fix, type: docs, type: chore, type: testing, or breaking): this is what both the automated checks below and the release changelog (see Releasing) use to categorise your change. The .github/release.yml file defines the mapping.

GitHub Actions workflows

Workflow	Runs on	What it does
build-docs	On release or on demand	Builds and deploys this site
check-env-exports	PR or push touching pixi-related files	Checks pixi, pyproject and conda envs are in sync
conda-, pip & pixi-install-test	Push to main or dev, weekly or on demand	Tests pip, conda and pixi installations
lint	Every pull request	Correctness + style checks (see below)
pixi-update	Monthly	Updates the pixi.lock file
prepare-release	On demand	Prepares for new oac release
publish	On release	Publishes to (Test)PyPI
quick-test	Every push/PR to main or dev	Fast pixi sanity test
Dependabot	Monthly	Checks for dependency updates

Learn more about the individual checks in the dropdown below.

build-docs.yml

build-docs.yml builds the documentation and deploys it to openairclim.org whenever a GitHub Release is published, so the live documentation matches the latest release on PyPI/conda-forge. The OpenAirClim version the documentation was built with is shown in the sidebar, below the project name.

The workflow can also be triggered manually via workflow_dispatch, e.g. to publish a documentation fix between releases. Manual runs from main or a tag deploy the result; manual runs from any other branch only build the documentation, which is useful to check that it builds. For builds that are not from a release tag, the sidebar also shows the (linked) commit hash the documentation was built from, since the live documentation may then be ahead of the latest release. We are exploring ways to host documentation per-release - see issue #104. This workflow also calculates the pytest code coverage.

check-env-exports.yml

pixi.lock and environment.yaml/environment_dev.yaml are all derived from the dependencies declared in pyproject.toml - the lock file by pixi itself, the yaml files by pixi run export-envs (see scripts/export-envs.sh). Nothing keeps them in sync automatically if someone edits a dependency and forgets to regenerate them, so this workflow checks it instead:

• pixi lock --check fails if pixi.lock is out of date with pyproject.toml.

• Regenerating environment.yaml/environment_dev.yaml and diffing the result against what is committed fails if they are stale.

It only runs when a commit touches pyproject.toml, pixi.lock, scripts/export-envs.sh or the environment*.yaml files themselves.

pip- & conda-install-test.yml

pip-install-test.yml and conda-install-test.yml test packaging rather than code correctness, so unlike quick-test.yml they don’t run on every PR - only on push to main/dev, weekly (to catch dependency drift during quieter development periods), and manually via workflow_dispatch.

pixi-install-test.yml

pixi-install-test.yml runs on the same schedule as the pip and conda checks above, but checks something different. Since pixi.lock pins every dependency, there is no drift to catch. The risk this test is designed to mitigate is instead that the locked environment doesn’t actually work on a platform other than the one you last ran pixi install on. This matters because some dependencies have a separate wheel per operating system.

lint.yml

The linting workflow runs two independent jobs on Python files changed in the PR.

• correctness (mypy and pyflakes (through ruff)) is a required check - a PR cannot be merged while it fails.

• style (ruff check and format) is not required. This job always completes successfully regardless of what it finds, so it can never block a merge on its own. On GitHub, an automated bot will add comments with style recommendations to any new PR (if it finds any).

Both jobs run in the locked pixi dev environment, so the ruff and mypy versions match those you use locally. The correctness job runs the same corr-ruff/corr-mypy pixi tasks as pixi run correctness. You can run the same checks locally before opening a PR. See Running code quality checks in the installation guide.

pixi-update.yml

Runs pixi update and checks for differences between the newly generated and current pixi.lock files. This way, any updates in OpenAirClim’s dependencies flow into the lock file, even if there haven’t been any recent commits to main. This workflow also runs the pytest functions to ensure that upgrading the dependencies doesn’t cause problems.

prepare-release.yml

See Releasing.

publish.yml

See Releasing.

quick-test.yml

A fast, single-configuration sanity check that runs on every push/PR to main and dev, for quick feedback on code correctness. It installs the dev environment from pixi.lock (faster than installing with pip), generates the test fixtures and runs the full pytest test suite. Installation with pip is tested by pip-install-test.yml instead.

Dependabot

The GitHub dependabot keeps things patched automatically. It opens monthly pull requests (up to 10 open at a time) bumping Python dependencies in pyproject.toml and GitHub Actions versions in .github/workflows/. These carry Dependabot’s own dependencies/github_actions labels.