Skip to content

Maintainer Guide

This guide describes the day-to-day responsibilities for Agent Lightning maintainers—how to bump versions, run release ceremonies, interact with CI, and backport fixes safely.

Release Workflow

Follow this checklist throughout each release cycle.

Immediately After Shipping

Agent Lightning uses a bump-first strategy. As soon as a release is published:

  1. Update version metadata:
    • pyproject.toml: bump the version.
    • agentlightning/__init__.py: update __version__ if it exists.
    • uv.lock: refresh the lock file after the bump.

  2. Refresh dependency pins as needed: 

    uv lock --upgrade

  3. For a new minor or major release, create a stable branch from main: 

    git checkout main
git pull upstream main
git checkout -b stable/v2.0.x  # adjust to the new series
git push upstream stable/v2.0.x

    All future changes to the stable branch must land via pull requests.

Preparing the Next Release

When it is time to publish the next version:

  1. Draft release notes in docs/changelog.md, collecting every notable change since the previous tag.
  2. Open a release PR targeting main (for minor/major) or the relevant stable branch (for patch releases). Use the title [Release] vX.Y.Z.
  3. Run extended CI by labeling the PR with ci-all and commenting /ci. Investigate and resolve any failures.
  4. Merge the release PR once notes are final and CI is green.

  5. Tag the release from the branch you just merged into:

    git checkout main          # minor/major releases
git checkout stable/vX.Y.Z # patch releases

git pull
git tag vX.Y.Z -m "Release vX.Y.Z"
git push upstream vX.Y.Z

    Pushing the tag publishes to PyPI and deploys the documentation.

  6. Publish the GitHub release using the drafted notes, and confirm the docs site and PyPI listing reflect the new version.

Working with CI Labels and /ci

GPU suites and example end-to-end runs are opt-in. To trigger them on a pull request:

  1. Apply the appropriate labels before issuing the command:
    • ci-all for every repository-dispatch workflow.
    • ci-gpu for GPU integration tests (tests-full.yml).
    • ci-apo, ci-calc-x, ci-spider, ci-unsloth, ci-compat for the individual example pipelines.
  2. Comment /ci on the PR. The issue-comment workflow acknowledges the request and tracks job results inline.
  3. Remove the labels once you have the signal to avoid accidental re-runs.

Use /ci whenever changes touch shared infrastructure, dependencies, or training loops that require coverage beyond the default PR checks.

Note

/ci always executes the workflow definitions on the current main branch, then checks out the PR diff. If you need to test workflow modifications, push the changes to a branch in the upstream repo and run:

gh workflow run examples-xxx.yml --ref your-branch-name

Backporting Pull Requests

Supported stable branches rely on automated backports:

  1. Identify the target branch (for example stable/v0.2.x).
  2. Before merging the original PR into main, add the matching stable/<series> label (e.g. stable/v0.2.x).
  3. The backport.yml workflow opens a follow-up PR named backport/<original-number>/<target-branch> authored by agent-lightning-bot.
  4. Review the generated PR, ensure CI is green, and merge into the stable branch.
  5. Resolve conflicts by pushing manual fixes to the backport branch and re-running /ci if required.

Keep stable branches healthy by cherry-picking only critical fixes and ensuring documentation and example metadata stay aligned with each release line.