From db457cf378392392f38dd960de197edd7a356275 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 29 Oct 2025 11:11:19 +0800 Subject: [PATCH 1/5] docs: add contributor and maintainer guides --- README.md | 2 +- docs/community/contributing.md | 109 +++++++++++++++++++++++++++++++++ docs/community/maintainers.md | 77 +++++++++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 190 insertions(+), 1 deletion(-) create mode 100644 docs/community/contributing.md create mode 100644 docs/community/maintainers.md diff --git a/README.md b/README.md index c58e7b6ad..d7627aded 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ If you find Agent Lightning useful in your research or projects, please cite our ## ⚡ Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. +This project welcomes contributions and suggestions. Start by reading the [Contributing Guide](docs/community/contributing.md) for environment setup, branching conventions, and pull request expectations. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 000000000..34964ab8e --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,109 @@ +# Contributing Guide + +Agent Lightning welcomes contributions of all sizes—from bug fixes to new features and documentation. +This guide walks you through getting a local environment ready, following our branching strategy, and opening a high-quality pull request. + +## 1. Prepare Your Environment + +### Prerequisites + +- **Python**: Version 3.10 or newer (the project is tested on 3.10–3.13). +- **uv**: We use [uv](https://docs.astral.sh/uv/) for dependency management and packaging speed. Install it via the instructions in the [official docs](https://docs.astral.sh/uv/getting-started/installation/). +- **Git**: Ensure you have Git installed and configured with your GitHub account. + +### Clone the Repository + +Fork the repository on GitHub, then clone your fork and add the upstream remote: + +```bash +git clone git@github.com:/agent-lightning.git +cd agent-lightning +git remote add upstream https://github.com/microsoft/agent-lightning.git +``` + +### Sync Dependencies + +Install the development toolchain with uv: + +```bash +uv sync --group dev +``` + +Need the full experience (algorithms, examples, GPU extras)? Enable the appropriate groups in one command: + +```bash +uv sync --frozen \ + --extra apo \ + --extra verl \ + --group dev \ + --group torch-cpu \ + --group torch-stable \ + --group trl \ + --group agents \ + --no-default-groups +``` + +After `uv sync`, either prefix commands with `uv run …` or activate the virtual environment from `.venv/`. + +## 2. Install and Run Pre-commit + +Code style and linting are enforced via [pre-commit](https://pre-commit.com/). Install the hooks once and run them before you push: + +```bash +uv run pre-commit install +uv run pre-commit run --all-files --show-diff-on-failure --color=always +``` + +Running the hooks locally saves you from CI failures and keeps diffs clean. + +## 3. Branching Workflow + +1. Always start from an up-to-date `main`: + ```bash + git fetch upstream + git checkout main + git merge upstream/main + ``` +2. Create a topic branch using one of the naming prefixes below: + - `feature/` — new features + - `fix/` — bug fixes + - `docs/` — documentation-only updates + - `chore/` — tooling or maintenance tweaks + +Use lowercase words separated by hyphens (e.g. `feature/async-runner-hooks`). + +## 4. Build and Validate Documentation + +If your change touches documentation, verify it builds cleanly: + +```bash +uv run mkdocs serve --strict # live reload during editing +uv run mkdocs build --strict # CI-equivalent check +``` + +The `--strict` flag matches our CI settings and turns warnings into errors so you can catch issues early. + +## 5. Before You Push + +- Run the pre-commit hooks (`uv run pre-commit run --all-files`). +- Execute the relevant tests, for example: + ```bash + uv run pytest -v tests + ``` +- For changes affecting examples, follow the README inside each `examples//` directory to validate manually as needed. + +## 6. Open a Pull Request + +1. Push your branch to your fork: + ```bash + git push origin + ``` +2. Open a pull request against `microsoft/agent-lightning:main`. +3. Fill out the PR description with: + - A summary of the change. + - A checklist of tests or commands you ran. + - Links to related issues (use `Fixes #123` to auto-close). +4. Add screenshots or terminal output when they help reviewers understand the change. +5. Respond to review feedback promptly; keep commits focused and consider using fixup commits (`git commit --fixup`) for clarity. + +Thank you for contributing—your improvements help the entire Agent Lightning community! diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md new file mode 100644 index 000000000..f4d181165 --- /dev/null +++ b/docs/community/maintainers.md @@ -0,0 +1,77 @@ +# Maintainer Guide + +This guide documents the day-to-day workflows for the Agent Lightning maintainers, including how to cut a release, interact with CI, and backport fixes. + +## Release Workflow + +Follow this checklist when preparing a new release. + +1. **Plan the scope** + - Collect the PRs and issues targeted for the release. + - Verify that required documentation updates are complete. + +2. **Create a release branch** + ```bash + git fetch upstream + git checkout -b release/vX.Y.Z upstream/main + ``` + +3. **Bump versions** + - Update `pyproject.toml` (and `agentlightning/__init__.py` if present) using the helper script: + ```bash + ./scripts/bump_version.sh X.Y.Z + ``` + - Commit the version bump separately so it is easy to cherry-pick later. + +4. **Update release collateral** + - Ensure the examples catalog at `examples/README.md` accurately reflects maintenance status and CI badges. + - Review the API reference pages in `docs/reference/` for outdated signatures or docstrings. + - Draft release notes in `docs/releases/` (create a new file for the version if necessary) and summarize key changes. Copy the same content into the GitHub release body later. + +5. **Run local checks** + - Install/update dependencies (`uv sync --group dev`). + - Run formatting and linting: `uv run pre-commit run --all-files --show-diff-on-failure`. + - Execute targeted tests, especially those touched by the release. + - Build docs exactly like CI: `uv run mkdocs build --strict`. + +6. **Open the release PR** + - Push the branch to the upstream repository if you have permission, otherwise to your fork. + - Title suggestion: `Release vX.Y.Z`. + - Link all relevant issues and include a checklist of validation steps. + - Apply the appropriate CI labels (see below) and comment `/ci` to exercise GPU/examples pipelines when needed. + +7. **Finalize the release** + - After the PR merges, create a signed tag that matches the version: + ```bash + git checkout main + git pull upstream main + git tag -s vX.Y.Z -m "Release vX.Y.Z" + git push upstream vX.Y.Z + ``` + - Pushing the tag triggers the PyPI publish and documentation deployment workflows. + - Create the GitHub release using the prepared notes, attach built artifacts if desired, and verify that the docs site shows the new version. + +## Working with CI Labels and `/ci` + +Long-running jobs such as GPU training or example end-to-end runs are opt-in on pull requests. To trigger them: + +1. Add one or more of the following labels to the PR before issuing the command: + - `ci-all` — run every repository-dispatch aware workflow. + - `ci-gpu` — run the GPU integration tests (`tests-full.yml`). + - `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat` — run the corresponding example pipelines. +2. Comment `/ci` on the pull request. The `issue-comment` workflow will acknowledge the command and track results inline. +3. Remove labels once the signal is collected to avoid accidental re-triggers. + +Use `/ci` whenever a change affects shared infrastructure, dependencies, or training logic that requires extra validation beyond the default PR checks. + +## Backporting Pull Requests + +We rely on automated backports for supported stable branches. + +1. Decide which stable branch should receive the fix (for example, `stable/v0.2`). +2. Before or immediately after merging the PR into `main`, add a label matching `stable/` (e.g., `stable/v0.2`). +3. The `backport.yml` workflow creates a new PR named `backport//` authored by `agent-lightning-bot`. +4. Review the generated backport PR, ensure CI passes, and merge it into the target branch. +5. If conflicts arise, push manual fixes directly to the backport branch and re-run `/ci` as needed. + +Keep the stable branches healthy by cherry-picking only critical fixes and ensuring their documentation and example metadata stay in sync with the release lines. diff --git a/mkdocs.yml b/mkdocs.yml index 918eb3354..7e9c0ccb0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,6 +123,9 @@ nav: - Trainer: reference/trainer.md - Types: reference/types.md - Internal: reference/internal.md + - Community: + - Contributing Guide: community/contributing.md + - Maintainer Guide: community/maintainers.md extra_css: - https://unpkg.com/katex@0/dist/katex.min.css From 5fe5271c787279bfb68e5794549ccbeadf5116f9 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Wed, 29 Oct 2025 18:16:39 +0800 Subject: [PATCH 2/5] Expand contributor testing guidance --- docs/community/contributing.md | 40 ++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 34964ab8e..96b2d1be5 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -72,7 +72,36 @@ Running the hooks locally saves you from CI failures and keeps diffs clean. Use lowercase words separated by hyphens (e.g. `feature/async-runner-hooks`). -## 4. Build and Validate Documentation +## 4. Run Tests and Checks + +Most code changes should be backed by automated tests. Use the `uv run` prefix so the commands execute inside the project virtual environment. + +- **Run the full test suite:** + ```bash + uv run pytest -v + ``` +- **Target a specific module or test:** + ```bash + uv run pytest tests/path/to/test_file.py -k test_name + ``` +- **Exercise optional markers:** We classify slower or optional suites with markers. For example, to skip anything marked `slow` + (the default in CI) run: + ```bash + uv run pytest -m "not slow" + ``` + To include GPU- or example-heavy paths locally, opt in with `-m slow` or the relevant marker listed at the top of the test file. +- **Collect coverage details (optional but helpful for large changes):** + ```bash + uv run pytest --cov=agentlightning --cov-report=term-missing + ``` +- **Type checking:** + ```bash + uv run pyright + ``` + +When touching integrations located in `examples/`, review the README inside each example directory for additional smoke-test instructions. + +## 5. Build and Validate Documentation If your change touches documentation, verify it builds cleanly: @@ -83,16 +112,13 @@ uv run mkdocs build --strict # CI-equivalent check The `--strict` flag matches our CI settings and turns warnings into errors so you can catch issues early. -## 5. Before You Push +## 6. Before You Push - Run the pre-commit hooks (`uv run pre-commit run --all-files`). -- Execute the relevant tests, for example: - ```bash - uv run pytest -v tests - ``` +- Execute the relevant tests (see the previous section for examples). - For changes affecting examples, follow the README inside each `examples//` directory to validate manually as needed. -## 6. Open a Pull Request +## 7. Open a Pull Request 1. Push your branch to your fork: ```bash From 463fa34db2336813a72d668ced916854500a6ab8 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Fri, 31 Oct 2025 19:22:36 +0800 Subject: [PATCH 3/5] . --- docs/community/contributing.md | 111 +++++++++++++++++++-------------- docs/community/maintainers.md | 107 ++++++++++++++++--------------- 2 files changed, 119 insertions(+), 99 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 96b2d1be5..cb5848608 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -1,9 +1,9 @@ # Contributing Guide -Agent Lightning welcomes contributions of all sizes—from bug fixes to new features and documentation. +Agent Lightning welcomes contributions of all sizes: from bug fixes to new features and documentation. This guide walks you through getting a local environment ready, following our branching strategy, and opening a high-quality pull request. -## 1. Prepare Your Environment +## Step 1. Prepare Your Environment ### Prerequisites @@ -38,14 +38,15 @@ uv sync --frozen \ --group dev \ --group torch-cpu \ --group torch-stable \ - --group trl \ --group agents \ --no-default-groups ``` -After `uv sync`, either prefix commands with `uv run …` or activate the virtual environment from `.venv/`. +After `uv sync`, either prefix commands with `uv run ...` (or `uv run --no-sync` if you prefer), or activate the virtual environment from `.venv/`. -## 2. Install and Run Pre-commit +--- + +## Step 2. Install and Run Pre-commit Code style and linting are enforced via [pre-commit](https://pre-commit.com/). Install the hooks once and run them before you push: @@ -56,52 +57,60 @@ uv run pre-commit run --all-files --show-diff-on-failure --color=always Running the hooks locally saves you from CI failures and keeps diffs clean. -## 3. Branching Workflow +--- -1. Always start from an up-to-date `main`: - ```bash - git fetch upstream - git checkout main - git merge upstream/main - ``` -2. Create a topic branch using one of the naming prefixes below: - - `feature/` — new features - - `fix/` — bug fixes - - `docs/` — documentation-only updates - - `chore/` — tooling or maintenance tweaks +## Step 3. Branching Workflow + +Always start from an up-to-date `main`: + +```bash +git fetch upstream +git checkout main +git merge upstream/main +``` + +Create a topic branch using one of the naming prefixes below: + +- `feature/` — new features +- `fix/` — bug fixes +- `docs/` — documentation-only updates +- `chore/` — tooling or maintenance tweaks Use lowercase words separated by hyphens (e.g. `feature/async-runner-hooks`). -## 4. Run Tests and Checks +--- + +## Step 4. Run Tests and Checks Most code changes should be backed by automated tests. Use the `uv run` prefix so the commands execute inside the project virtual environment. -- **Run the full test suite:** - ```bash - uv run pytest -v - ``` -- **Target a specific module or test:** - ```bash - uv run pytest tests/path/to/test_file.py -k test_name - ``` -- **Exercise optional markers:** We classify slower or optional suites with markers. For example, to skip anything marked `slow` - (the default in CI) run: - ```bash - uv run pytest -m "not slow" - ``` - To include GPU- or example-heavy paths locally, opt in with `-m slow` or the relevant marker listed at the top of the test file. -- **Collect coverage details (optional but helpful for large changes):** - ```bash - uv run pytest --cov=agentlightning --cov-report=term-missing - ``` -- **Type checking:** - ```bash - uv run pyright - ``` +**Run the full test suite:** + +```bash +uv run pytest -v +``` + +**Target a specific module or test:** + +```bash +uv run pytest tests/path/to/test_file.py -k test_name +``` + +**Run optional tests:** + +When you have a GPU or have an environment set up like `OPENAI_API_KEY`, related tests will be included and run automatically. + +**Type checking:** + +```bash +uv run pyright +``` When touching integrations located in `examples/`, review the README inside each example directory for additional smoke-test instructions. -## 5. Build and Validate Documentation +--- + +## Step 5. Build and Validate Documentation If your change touches documentation, verify it builds cleanly: @@ -112,13 +121,17 @@ uv run mkdocs build --strict # CI-equivalent check The `--strict` flag matches our CI settings and turns warnings into errors so you can catch issues early. -## 6. Before You Push +--- + +## Step 6. Before You Push -- Run the pre-commit hooks (`uv run pre-commit run --all-files`). +- Run the pre-commit hooks (`uv run pre-commit run --all-files`). If you have installed the hooks, the Git client will run them automatically on `git commit`. - Execute the relevant tests (see the previous section for examples). - For changes affecting examples, follow the README inside each `examples//` directory to validate manually as needed. -## 7. Open a Pull Request +--- + +## Step 7. Open a Pull Request 1. Push your branch to your fork: ```bash @@ -126,10 +139,12 @@ The `--strict` flag matches our CI settings and turns warnings into errors so yo ``` 2. Open a pull request against `microsoft/agent-lightning:main`. 3. Fill out the PR description with: - - A summary of the change. - - A checklist of tests or commands you ran. - - Links to related issues (use `Fixes #123` to auto-close). + + - A summary of the change. + - A checklist of tests or commands you ran. + - Links to related issues (use `Fixes #123` to auto-close). + 4. Add screenshots or terminal output when they help reviewers understand the change. 5. Respond to review feedback promptly; keep commits focused and consider using fixup commits (`git commit --fixup`) for clarity. -Thank you for contributing—your improvements help the entire Agent Lightning community! +Thank you for contributing. Your improvements help the entire Agent Lightning community! diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md index f4d181165..074fd4646 100644 --- a/docs/community/maintainers.md +++ b/docs/community/maintainers.md @@ -4,61 +4,66 @@ This guide documents the day-to-day workflows for the Agent Lightning maintainer ## Release Workflow -Follow this checklist when preparing a new release. - -1. **Plan the scope** - - Collect the PRs and issues targeted for the release. - - Verify that required documentation updates are complete. - -2. **Create a release branch** - ```bash - git fetch upstream - git checkout -b release/vX.Y.Z upstream/main - ``` - -3. **Bump versions** - - Update `pyproject.toml` (and `agentlightning/__init__.py` if present) using the helper script: - ```bash - ./scripts/bump_version.sh X.Y.Z - ``` - - Commit the version bump separately so it is easy to cherry-pick later. - -4. **Update release collateral** - - Ensure the examples catalog at `examples/README.md` accurately reflects maintenance status and CI badges. - - Review the API reference pages in `docs/reference/` for outdated signatures or docstrings. - - Draft release notes in `docs/releases/` (create a new file for the version if necessary) and summarize key changes. Copy the same content into the GitHub release body later. - -5. **Run local checks** - - Install/update dependencies (`uv sync --group dev`). - - Run formatting and linting: `uv run pre-commit run --all-files --show-diff-on-failure`. - - Execute targeted tests, especially those touched by the release. - - Build docs exactly like CI: `uv run mkdocs build --strict`. - -6. **Open the release PR** - - Push the branch to the upstream repository if you have permission, otherwise to your fork. - - Title suggestion: `Release vX.Y.Z`. - - Link all relevant issues and include a checklist of validation steps. - - Apply the appropriate CI labels (see below) and comment `/ci` to exercise GPU/examples pipelines when needed. - -7. **Finalize the release** - - After the PR merges, create a signed tag that matches the version: - ```bash - git checkout main - git pull upstream main - git tag -s vX.Y.Z -m "Release vX.Y.Z" - git push upstream vX.Y.Z - ``` - - Pushing the tag triggers the PyPI publish and documentation deployment workflows. - - Create the GitHub release using the prepared notes, attach built artifacts if desired, and verify that the docs site shows the new version. +Follow this checklist throughout a release cycle. + +### After the Last Release + +We start from the time when the previous release has just been out. + +Agent-lightning follows a **bump version first** strategy. We bump to next version immediately after a release is out. To bump the version, update the following files: + +- `pyproject.toml`: Update the `version` field. +- `agentlightning/__init__.py`: Update the `__version__` variable if present. +- `uv.lock`: Run `uv lock` to update the lockfile with the new version. + +We also bump dependency versions as needed to keep up with ecosystem changes. + +```bash +uv lock --upgrade +``` + +If the last release is a new major or minor version, create a new stable branch from `main`: + +```bash +git checkout main +git pull upstream main +git checkout -b stable/v2.0.x # <-- adjust version as needed +git push upstream stable/v2.0.x +``` + +Notice that the stable branch requires merging via pull requests once you have pushed it to the upstream remote. + +### Preparing for a New Release + +When it's time to prepare a new release, follow these steps below. + +1. **Prepare Release Note Draft**: Start collecting all the changes since the last release, and write the changes in `docs/changelog.md` under a new heading for the upcoming version. +2. **Open a Pull Request**: Open a PR against `main` (if it's a minor/major release) or the relevant stable branch (if it's a patch release) with the draft release notes. Use the title `[Release] vX.Y.Z`. +3. **Run CI checks**: Label the PR with `ci-all` and comment `/ci` to run all the tests, including GPU and example pipelines. Address any issues that arise. +4. **Merge the release PR**: Once all checks pass and the release notes are finalized, merge the PR. +5. **Create a tag for the release**: After merging, create a tag that matches the version: + + ```bash + git checkout main # <-- if it's a minor/major release + git checkout stable/vX.Y.Z # <-- if it's a patch release + + git pull + git tag vX.Y.Z -m "Release vX.Y.Z" + git push upstream vX.Y.Z + ``` + + Pushing the tag triggers the PyPI publish and documentation deployment workflows. + +6. **Create the GitHub release**: Use the prepared notes from the PR to create a new GitHub release. Verify that the docs site shows the new version and the new package are available on PyPI. ## Working with CI Labels and `/ci` Long-running jobs such as GPU training or example end-to-end runs are opt-in on pull requests. To trigger them: 1. Add one or more of the following labels to the PR before issuing the command: - - `ci-all` — run every repository-dispatch aware workflow. - - `ci-gpu` — run the GPU integration tests (`tests-full.yml`). - - `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat` — run the corresponding example pipelines. + - `ci-all` — run every repository-dispatch aware workflow. + - `ci-gpu` — run the GPU integration tests (`tests-full.yml`). + - `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat` — run the corresponding example pipelines. 2. Comment `/ci` on the pull request. The `issue-comment` workflow will acknowledge the command and track results inline. 3. Remove labels once the signal is collected to avoid accidental re-triggers. @@ -68,8 +73,8 @@ Use `/ci` whenever a change affects shared infrastructure, dependencies, or trai We rely on automated backports for supported stable branches. -1. Decide which stable branch should receive the fix (for example, `stable/v0.2`). -2. Before or immediately after merging the PR into `main`, add a label matching `stable/` (e.g., `stable/v0.2`). +1. Decide which stable branch should receive the fix (for example, `stable/v0.2.x`). +2. Before merging the PR into `main`, add a label matching `stable/` (e.g., `stable/v0.2.x`). 3. The `backport.yml` workflow creates a new PR named `backport//` authored by `agent-lightning-bot`. 4. Review the generated backport PR, ensure CI passes, and merge it into the target branch. 5. If conflicts arise, push manual fixes directly to the backport branch and re-run `/ci` as needed. From 8b86d6421a695ef110e46859842efff4b382bb90 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Fri, 31 Oct 2025 19:44:37 +0800 Subject: [PATCH 4/5] . --- docs/community/maintainers.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md index 074fd4646..cbedaff6d 100644 --- a/docs/community/maintainers.md +++ b/docs/community/maintainers.md @@ -69,6 +69,14 @@ Long-running jobs such as GPU training or example end-to-end runs are opt-in on Use `/ci` whenever a change affects shared infrastructure, dependencies, or training logic that requires extra validation beyond the default PR checks. +!!! note + + When invoking `/ci` on PR, the workflow always runs against the workflow defined on the main branch. It then checks out the PR changes within the workflow. So if you need to modify the workflow itself, push the changes to a branch on the first-party repository first, and then run: + + ```bash + gh workflow run examples-xxx.yml --ref your-branch-name + ``` + ## Backporting Pull Requests We rely on automated backports for supported stable branches. From 5948849f5692e606bde859d4235f04e22d1f5b52 Mon Sep 17 00:00:00 2001 From: Yuge Zhang Date: Sat, 1 Nov 2025 12:43:16 +0800 Subject: [PATCH 5/5] refine language --- docs/community/contributing.md | 93 ++++++++++++++++---------------- docs/community/maintainers.md | 98 ++++++++++++++++------------------ 2 files changed, 93 insertions(+), 98 deletions(-) diff --git a/docs/community/contributing.md b/docs/community/contributing.md index cb5848608..81754f48f 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -1,19 +1,18 @@ # Contributing Guide -Agent Lightning welcomes contributions of all sizes: from bug fixes to new features and documentation. -This guide walks you through getting a local environment ready, following our branching strategy, and opening a high-quality pull request. +Agent Lightning thrives on community improvements, whether you are polishing docs, fixing bugs, or building new features. This guide shows the shortest path from cloning the repository to shipping a polished pull request. ## Step 1. Prepare Your Environment ### Prerequisites -- **Python**: Version 3.10 or newer (the project is tested on 3.10–3.13). -- **uv**: We use [uv](https://docs.astral.sh/uv/) for dependency management and packaging speed. Install it via the instructions in the [official docs](https://docs.astral.sh/uv/getting-started/installation/). -- **Git**: Ensure you have Git installed and configured with your GitHub account. +- **Python** 3.10 or newer (we test on 3.10–3.13). +- **uv** for dependency and virtual environment management. Install it from the [official uv docs](https://docs.astral.sh/uv/getting-started/installation/). +- **Git** configured with your GitHub credentials. ### Clone the Repository -Fork the repository on GitHub, then clone your fork and add the upstream remote: +Fork the repo, then clone your fork and register the upstream remote so you can stay current: ```bash git clone git@github.com:/agent-lightning.git @@ -21,15 +20,15 @@ cd agent-lightning git remote add upstream https://github.com/microsoft/agent-lightning.git ``` -### Sync Dependencies +### Install Dependencies -Install the development toolchain with uv: +Install the standard development toolchain: ```bash uv sync --group dev ``` -Need the full experience (algorithms, examples, GPU extras)? Enable the appropriate groups in one command: +Want GPU extras, example dependencies, or other optional features? Pin everything in one pass: ```bash uv sync --frozen \ @@ -42,26 +41,28 @@ uv sync --frozen \ --no-default-groups ``` -After `uv sync`, either prefix commands with `uv run ...` (or `uv run --no-sync` if you prefer), or activate the virtual environment from `.venv/`. +After `uv sync`, run commands with `uv run ...` (or `uv run --no-sync` once the environment is locked), or activate the virtual environment in `.venv/`. --- ## Step 2. Install and Run Pre-commit -Code style and linting are enforced via [pre-commit](https://pre-commit.com/). Install the hooks once and run them before you push: +We enforce formatting and linting with [pre-commit](https://pre-commit.com/). Install the hooks once, then run them before every push: ```bash uv run pre-commit install + +# The following will auto-run if you have set up the pre-commit hooks to run automatically on commit. uv run pre-commit run --all-files --show-diff-on-failure --color=always ``` -Running the hooks locally saves you from CI failures and keeps diffs clean. +Running them locally saves a CI round-trip and keeps diffs tidy. --- ## Step 3. Branching Workflow -Always start from an up-to-date `main`: +Start from a fresh `main`, then branch for your change: ```bash git fetch upstream @@ -69,65 +70,65 @@ git checkout main git merge upstream/main ``` -Create a topic branch using one of the naming prefixes below: +Create a topic branch with one of these prefixes: -- `feature/` — new features -- `fix/` — bug fixes -- `docs/` — documentation-only updates -- `chore/` — tooling or maintenance tweaks +- `feature/` for new features +- `fix/` for bug fixes +- `docs/` for documentation-only work +- `chore/` for tooling or maintenance -Use lowercase words separated by hyphens (e.g. `feature/async-runner-hooks`). +Stick to lowercase words separated by hyphens, e.g. `feature/async-runner-hooks`. --- -## Step 4. Run Tests and Checks +## Step 4. Test Your Changes -Most code changes should be backed by automated tests. Use the `uv run` prefix so the commands execute inside the project virtual environment. +Most updates should ship with automated checks. Preface commands with `uv run` so they use the project environment. -**Run the full test suite:** +**Full test suite** ```bash uv run pytest -v ``` -**Target a specific module or test:** +**Targeted tests** ```bash uv run pytest tests/path/to/test_file.py -k test_name ``` -**Run optional tests:** +**Optional/gated tests** -When you have a GPU or have an environment set up like `OPENAI_API_KEY`, related tests will be included and run automatically. +GPU-specific suites or API-dependent tests run automatically when the required hardware or environment variables (such as `OPENAI_API_KEY`) are present. -**Type checking:** +**Static analysis** ```bash uv run pyright ``` -When touching integrations located in `examples/`, review the README inside each example directory for additional smoke-test instructions. +Touching code under `examples/`? Each directory includes a README with example-specific smoke tests—run those too. --- -## Step 5. Build and Validate Documentation +## Step 5. Build Documentation (When Applicable) -If your change touches documentation, verify it builds cleanly: +Doc changes should build cleanly before you push: ```bash -uv run mkdocs serve --strict # live reload during editing -uv run mkdocs build --strict # CI-equivalent check +uv run mkdocs serve --strict # live reload while editing +uv run mkdocs build --strict # CI-equivalent validation ``` -The `--strict` flag matches our CI settings and turns warnings into errors so you can catch issues early. +`--strict` matches CI and promotes warnings to errors so you catch them early. --- -## Step 6. Before You Push +## Step 6. Final Local Checks -- Run the pre-commit hooks (`uv run pre-commit run --all-files`). If you have installed the hooks, the Git client will run them automatically on `git commit`. -- Execute the relevant tests (see the previous section for examples). -- For changes affecting examples, follow the README inside each `examples//` directory to validate manually as needed. +- Run `uv run pre-commit run --all-files` (hooks installed via `pre-commit install` run automatically on `git commit`, but rerun them if you amended history). +- Execute the relevant test commands from Step 4. +- Validate any affected examples by following the instructions in `examples//README`. --- @@ -137,14 +138,12 @@ The `--strict` flag matches our CI settings and turns warnings into errors so yo ```bash git push origin ``` -2. Open a pull request against `microsoft/agent-lightning:main`. -3. Fill out the PR description with: - - - A summary of the change. - - A checklist of tests or commands you ran. - - Links to related issues (use `Fixes #123` to auto-close). - -4. Add screenshots or terminal output when they help reviewers understand the change. -5. Respond to review feedback promptly; keep commits focused and consider using fixup commits (`git commit --fixup`) for clarity. - -Thank you for contributing. Your improvements help the entire Agent Lightning community! +2. Open a PR against `microsoft/agent-lightning:main`. +3. Complete the PR template with: + - A concise summary of the change. + - The tests or commands you ran (copy from Step 4/6). + - Linked issues (use `Fixes #123` to auto-close). +4. Attach screenshots or terminal output when it clarifies behavior. +5. Address review feedback promptly. Use focused commits, and consider `git commit --fixup` for follow-up adjustments. + +Thanks for contributing—every improvement grows the Agent Lightning community! diff --git a/docs/community/maintainers.md b/docs/community/maintainers.md index cbedaff6d..5da7c3875 100644 --- a/docs/community/maintainers.md +++ b/docs/community/maintainers.md @@ -1,77 +1,73 @@ # Maintainer Guide -This guide documents the day-to-day workflows for the Agent Lightning maintainers, including how to cut a release, interact with CI, and backport fixes. +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 a release cycle. +Follow this checklist throughout each release cycle. -### After the Last Release +### Immediately After Shipping -We start from the time when the previous release has just been out. +Agent Lightning uses a **bump-first** strategy. As soon as a release is published: -Agent-lightning follows a **bump version first** strategy. We bump to next version immediately after a release is out. To bump the version, update the following files: - -- `pyproject.toml`: Update the `version` field. -- `agentlightning/__init__.py`: Update the `__version__` variable if present. -- `uv.lock`: Run `uv lock` to update the lockfile with the new version. - -We also bump dependency versions as needed to keep up with ecosystem changes. - -```bash -uv lock --upgrade -``` - -If the last release is a new major or minor version, create a new stable branch from `main`: +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: + ```bash + uv lock --upgrade + ``` -```bash -git checkout main -git pull upstream main -git checkout -b stable/v2.0.x # <-- adjust version as needed -git push upstream stable/v2.0.x -``` +3. For a new minor or major release, create a stable branch from `main`: + ```bash + 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 + ``` -Notice that the stable branch requires merging via pull requests once you have pushed it to the upstream remote. + All future changes to the stable branch must land via pull requests. -### Preparing for a New Release +### Preparing the Next Release -When it's time to prepare a new release, follow these steps below. +When it is time to publish the next version: -1. **Prepare Release Note Draft**: Start collecting all the changes since the last release, and write the changes in `docs/changelog.md` under a new heading for the upcoming version. -2. **Open a Pull Request**: Open a PR against `main` (if it's a minor/major release) or the relevant stable branch (if it's a patch release) with the draft release notes. Use the title `[Release] vX.Y.Z`. -3. **Run CI checks**: Label the PR with `ci-all` and comment `/ci` to run all the tests, including GPU and example pipelines. Address any issues that arise. -4. **Merge the release PR**: Once all checks pass and the release notes are finalized, merge the PR. -5. **Create a tag for the release**: After merging, create a tag that matches the 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: ```bash - git checkout main # <-- if it's a minor/major release - git checkout stable/vX.Y.Z # <-- if it's a patch release + 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 triggers the PyPI publish and documentation deployment workflows. + Pushing the tag publishes to PyPI and deploys the documentation. -6. **Create the GitHub release**: Use the prepared notes from the PR to create a new GitHub release. Verify that the docs site shows the new version and the new package are available on PyPI. +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` -Long-running jobs such as GPU training or example end-to-end runs are opt-in on pull requests. To trigger them: +GPU suites and example end-to-end runs are opt-in. To trigger them on a pull request: -1. Add one or more of the following labels to the PR before issuing the command: - - `ci-all` — run every repository-dispatch aware workflow. - - `ci-gpu` — run the GPU integration tests (`tests-full.yml`). - - `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat` — run the corresponding example pipelines. -2. Comment `/ci` on the pull request. The `issue-comment` workflow will acknowledge the command and track results inline. -3. Remove labels once the signal is collected to avoid accidental re-triggers. +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 a change affects shared infrastructure, dependencies, or training logic that requires extra validation beyond the default PR checks. +Use `/ci` whenever changes touch shared infrastructure, dependencies, or training loops that require coverage beyond the default PR checks. !!! note - When invoking `/ci` on PR, the workflow always runs against the workflow defined on the main branch. It then checks out the PR changes within the workflow. So if you need to modify the workflow itself, push the changes to a branch on the first-party repository first, and then run: + `/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: ```bash gh workflow run examples-xxx.yml --ref your-branch-name @@ -79,12 +75,12 @@ Use `/ci` whenever a change affects shared infrastructure, dependencies, or trai ## Backporting Pull Requests -We rely on automated backports for supported stable branches. +Supported stable branches rely on automated backports: -1. Decide which stable branch should receive the fix (for example, `stable/v0.2.x`). -2. Before merging the PR into `main`, add a label matching `stable/` (e.g., `stable/v0.2.x`). -3. The `backport.yml` workflow creates a new PR named `backport//` authored by `agent-lightning-bot`. -4. Review the generated backport PR, ensure CI passes, and merge it into the target branch. -5. If conflicts arise, push manual fixes directly to the backport branch and re-run `/ci` as needed. +1. Identify the target branch (for example `stable/v0.2.x`). +2. Before merging the original PR into `main`, add the matching `stable/` label (e.g. `stable/v0.2.x`). +3. The `backport.yml` workflow opens a follow-up PR named `backport//` 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 the stable branches healthy by cherry-picking only critical fixes and ensuring their documentation and example metadata stay in sync with the release lines. +Keep stable branches healthy by cherry-picking only critical fixes and ensuring documentation and example metadata stay aligned with each release line.