You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Agent Lightning welcomes contributions of all sizes: from bug fixes to new features and documentation.
4
-
This guide walks you through getting a local environment ready, following our branching strategy, and opening a high-quality pull request.
3
+
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.
5
4
6
5
## Step 1. Prepare Your Environment
7
6
8
7
### Prerequisites
9
8
10
-
-**Python**: Version 3.10 or newer (the project is tested on 3.10–3.13).
11
-
-**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/).
12
-
-**Git**: Ensure you have Git installed and configured with your GitHub account.
9
+
-**Python**3.10 or newer (we test on 3.10–3.13).
10
+
-**uv**for dependency and virtual environment management. Install it from the [official uv docs](https://docs.astral.sh/uv/getting-started/installation/).
11
+
-**Git**configured with your GitHub credentials.
13
12
14
13
### Clone the Repository
15
14
16
-
Fork the repository on GitHub, then clone your fork and add the upstream remote:
15
+
Fork the repo, then clone your fork and register the upstream remote so you can stay current:
-`chore/<short-description>`— tooling or maintenance tweaks
75
+
-`feature/<short-description>`for new features
76
+
-`fix/<short-description>`for bug fixes
77
+
-`docs/<short-description>`for documentation-only work
78
+
-`chore/<short-description>`for tooling or maintenance
78
79
79
-
Use lowercase words separated by hyphens (e.g. `feature/async-runner-hooks`).
80
+
Stick to lowercase words separated by hyphens, e.g. `feature/async-runner-hooks`.
80
81
81
82
---
82
83
83
-
## Step 4. Run Tests and Checks
84
+
## Step 4. Test Your Changes
84
85
85
-
Most code changes should be backed by automated tests. Use the `uv run`prefix so the commands execute inside the project virtual environment.
86
+
Most updates should ship with automated checks. Preface commands with `uv run` so they use the project environment.
86
87
87
-
**Run the full test suite:**
88
+
**Full test suite**
88
89
89
90
```bash
90
91
uv run pytest -v
91
92
```
92
93
93
-
**Target a specific module or test:**
94
+
**Targeted tests**
94
95
95
96
```bash
96
97
uv run pytest tests/path/to/test_file.py -k test_name
97
98
```
98
99
99
-
**Run optional tests:**
100
+
**Optional/gated tests**
100
101
101
-
When you have a GPUor have an environment set up like `OPENAI_API_KEY`, related tests will be included and run automatically.
102
+
GPU-specific suites or API-dependent tests run automatically when the required hardware or environment variables (such as `OPENAI_API_KEY`) are present.
102
103
103
-
**Type checking:**
104
+
**Static analysis**
104
105
105
106
```bash
106
107
uv run pyright
107
108
```
108
109
109
-
When touching integrations located in `examples/`, review the README inside each example directory for additional smoke-test instructions.
110
+
Touching code under `examples/`? Each directory includes a README with example-specific smoke tests—run those too.
110
111
111
112
---
112
113
113
-
## Step 5. Build and Validate Documentation
114
+
## Step 5. Build Documentation (When Applicable)
114
115
115
-
If your change touches documentation, verify it builds cleanly:
116
+
Doc changes should build cleanly before you push:
116
117
117
118
```bash
118
-
uv run mkdocs serve --strict # live reload during editing
119
-
uv run mkdocs build --strict # CI-equivalent check
119
+
uv run mkdocs serve --strict # live reload while editing
120
+
uv run mkdocs build --strict # CI-equivalent validation
120
121
```
121
122
122
-
The `--strict`flag matches our CI settings and turns warnings into errors so you can catch issues early.
123
+
`--strict` matches CI and promotes warnings to errors so you catch them early.
123
124
124
125
---
125
126
126
-
## Step 6. Before You Push
127
+
## Step 6. Final Local Checks
127
128
128
-
- 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`.
129
-
- Execute the relevant tests (see the previous section for examples).
130
-
-For changes affecting examples, follow the README inside each `examples/<name>/` directory to validate manually as needed.
129
+
- 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).
130
+
- Execute the relevant test commands from Step 4.
131
+
-Validate any affected examples by following the instructions in `examples/<name>/README`.
131
132
132
133
---
133
134
@@ -137,14 +138,12 @@ The `--strict` flag matches our CI settings and turns warnings into errors so yo
137
138
```bash
138
139
git push origin <branch-name>
139
140
```
140
-
2. Open a pull request against `microsoft/agent-lightning:main`.
141
-
3. Fill out the PR description with:
142
-
143
-
- A summary of the change.
144
-
- A checklist of tests or commands you ran.
145
-
- Links to related issues (use `Fixes #123` to auto-close).
146
-
147
-
4. Add screenshots or terminal output when they help reviewers understand the change.
148
-
5. Respond to review feedback promptly; keep commits focused and consider using fixup commits (`git commit --fixup`) for clarity.
149
-
150
-
Thank you for contributing. Your improvements help the entire Agent Lightning community!
141
+
2. Open a PR against `microsoft/agent-lightning:main`.
142
+
3. Complete the PR template with:
143
+
- A concise summary of the change.
144
+
- The tests or commands you ran (copy from Step 4/6).
145
+
- Linked issues (use `Fixes #123` to auto-close).
146
+
4. Attach screenshots or terminal output when it clarifies behavior.
147
+
5. Address review feedback promptly. Use focused commits, and consider `git commit --fixup` for follow-up adjustments.
148
+
149
+
Thanks for contributing—every improvement grows the Agent Lightning community!
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.
3
+
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.
4
4
5
5
## Release Workflow
6
6
7
-
Follow this checklist throughout a release cycle.
7
+
Follow this checklist throughout each release cycle.
8
8
9
-
### After the Last Release
9
+
### Immediately After Shipping
10
10
11
-
We start from the time when the previous release has just been out.
11
+
Agent Lightning uses a **bump-first** strategy. As soon as a release is published:
12
12
13
-
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:
14
-
15
-
-`pyproject.toml`: Update the `version` field.
16
-
-`agentlightning/__init__.py`: Update the `__version__` variable if present.
17
-
-`uv.lock`: Run `uv lock` to update the lockfile with the new version.
18
-
19
-
We also bump dependency versions as needed to keep up with ecosystem changes.
20
-
21
-
```bash
22
-
uv lock --upgrade
23
-
```
24
-
25
-
If the last release is a new major or minor version, create a new stable branch from `main`:
13
+
1. Update version metadata:
14
+
-`pyproject.toml`: bump the `version`.
15
+
-`agentlightning/__init__.py`: update `__version__` if it exists.
16
+
-`uv.lock`: refresh the lock file after the bump.
17
+
2. Refresh dependency pins as needed:
18
+
```bash
19
+
uv lock --upgrade
20
+
```
26
21
27
-
```bash
28
-
git checkout main
29
-
git pull upstream main
30
-
git checkout -b stable/v2.0.x # <-- adjust version as needed
31
-
git push upstream stable/v2.0.x
32
-
```
22
+
3. For a new minor or major release, create a stable branch from `main`:
23
+
```bash
24
+
git checkout main
25
+
git pull upstream main
26
+
git checkout -b stable/v2.0.x # adjust to the new series
27
+
git push upstream stable/v2.0.x
28
+
```
33
29
34
-
Notice that the stable branch requires merging via pull requests once you have pushed it to the upstream remote.
30
+
All future changes to the stable branch must land via pull requests.
35
31
36
-
### Preparing for a New Release
32
+
### Preparing the Next Release
37
33
38
-
When it's time to prepare a new release, follow these steps below.
34
+
When it is time to publish the next version:
39
35
40
-
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.
41
-
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`.
42
-
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.
43
-
4.**Merge the release PR**: Once all checks pass and the release notes are finalized, merge the PR.
44
-
5.**Create a tag for the release**: After merging, create a tag that matches the version:
36
+
1. **Draft release notes**in`docs/changelog.md`, collecting every notable change since the previous tag.
37
+
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`.
38
+
3. **Run extended CI** by labeling the PR with `ci-all` and commenting`/ci`. Investigate and resolve any failures.
39
+
4. **Merge the release PR** once notes are final and CI is green.
40
+
5. **Tag the release** from the branch you just merged into:
45
41
46
42
```bash
47
-
git checkout main # <-- if it's a minor/major release
48
-
git checkout stable/vX.Y.Z # <-- if it's a patch release
43
+
git checkout main #minor/major releases
44
+
git checkout stable/vX.Y.Z # patch releases
49
45
50
46
git pull
51
47
git tag vX.Y.Z -m "Release vX.Y.Z"
52
48
git push upstream vX.Y.Z
53
49
```
54
50
55
-
Pushing the tag triggers the PyPI publish and documentation deployment workflows.
51
+
Pushing the tag publishes to PyPI and deploys the documentation.
56
52
57
-
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.
53
+
6. **Publish the GitHub release** using the drafted notes, and confirm the docs site and PyPI listing reflect the new version.
58
54
59
55
## Working with CI Labels and `/ci`
60
56
61
-
Long-running jobs such as GPU training or example end-to-end runs are opt-in on pull requests. To trigger them:
57
+
GPU suites and example end-to-end runs are opt-in. To trigger them on a pull request:
62
58
63
-
1. Add one or more of the following labels to the PR before issuing the command:
64
-
- `ci-all`— run every repository-dispatch aware workflow.
65
-
- `ci-gpu`— run the GPU integration tests (`tests-full.yml`).
66
-
- `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat`— run the corresponding example pipelines.
67
-
2. Comment `/ci` on the pull request. The `issue-comment` workflow will acknowledge the command and track results inline.
68
-
3. Remove labels once the signal is collected to avoid accidental re-triggers.
59
+
1. Apply the appropriate labels before issuing the command:
- `ci-apo`, `ci-calc-x`, `ci-spider`, `ci-unsloth`, `ci-compat`forthe individual example pipelines.
63
+
2. Comment `/ci` on the PR. The `issue-comment` workflow acknowledges the request and tracks job results inline.
64
+
3. Remove the labels once you have the signal to avoid accidental re-runs.
69
65
70
-
Use `/ci` whenever a change affects shared infrastructure, dependencies, or training logic that requires extra validation beyond the default PR checks.
66
+
Use `/ci` whenever changes touch shared infrastructure, dependencies, or training loops that require coverage beyond the default PR checks.
71
67
72
68
!!! note
73
69
74
-
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 ifyou need to modify the workflow itself, push the changes to a branch on the first-party repository first, andthen run:
70
+
`/ci` always executes the workflow definitions on the current `main` branch, then checks out the PR diff. If you need to testworkflow modifications, push the changes to a branch in the upstream repo and run:
75
71
76
72
```bash
77
73
gh workflow run examples-xxx.yml --ref your-branch-name
78
74
```
79
75
80
76
## Backporting Pull Requests
81
77
82
-
We rely on automated backportsfor supported stable branches.
78
+
Supported stable branches rely on automated backports:
83
79
84
-
1. Decide which stable branch should receive the fix (for example,`stable/v0.2.x`).
85
-
2. Before merging the PR into `main`, add a label matching `stable/<series>` (e.g.,`stable/v0.2.x`).
86
-
3. The `backport.yml` workflow creates a new PR named `backport/<original-number>/<target-branch>` authored by `agent-lightning-bot`.
87
-
4. Review the generated backport PR, ensure CI passes, and merge it into the target branch.
88
-
5. If conflicts arise, push manual fixes directly to the backport branch and re-run`/ci`as needed.
80
+
1. Identify the target branch (for example `stable/v0.2.x`).
81
+
2. Before merging the original PR into `main`, add the matching `stable/<series>`label (e.g. `stable/v0.2.x`).
82
+
3. The `backport.yml` workflow opens a follow-up PR named `backport/<original-number>/<target-branch>` authored by `agent-lightning-bot`.
83
+
4. Review the generated PR, ensure CI is green, and merge into the stable branch.
84
+
5. Resolve conflicts by pushing manual fixes to the backport branch and re-running`/ci`if required.
89
85
90
-
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.
86
+
Keep stable branches healthy by cherry-picking only critical fixes and ensuring documentation and example metadata stay aligned with each release line.
0 commit comments