Add contributor and maintainer guides (#239)
This commit is contained in:
Yuge Zhang
@@ -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.
|
||||
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
# Contributing Guide
|
||||
|
||||
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** 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 repo, then clone your fork and register the upstream remote so you can stay current:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:<your-username>/agent-lightning.git
|
||||
cd agent-lightning
|
||||
git remote add upstream https://github.com/microsoft/agent-lightning.git
|
||||
```
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
Install the standard development toolchain:
|
||||
|
||||
```bash
|
||||
uv sync --group dev
|
||||
```
|
||||
|
||||
Want GPU extras, example dependencies, or other optional features? Pin everything in one pass:
|
||||
|
||||
```bash
|
||||
uv sync --frozen \
|
||||
--extra apo \
|
||||
--extra verl \
|
||||
--group dev \
|
||||
--group torch-cpu \
|
||||
--group torch-stable \
|
||||
--group agents \
|
||||
--no-default-groups
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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 them locally saves a CI round-trip and keeps diffs tidy.
|
||||
|
||||
---
|
||||
|
||||
## Step 3. Branching Workflow
|
||||
|
||||
Start from a fresh `main`, then branch for your change:
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git checkout main
|
||||
git merge upstream/main
|
||||
```
|
||||
|
||||
Create a topic branch with one of these prefixes:
|
||||
|
||||
- `feature/<short-description>` for new features
|
||||
- `fix/<short-description>` for bug fixes
|
||||
- `docs/<short-description>` for documentation-only work
|
||||
- `chore/<short-description>` for tooling or maintenance
|
||||
|
||||
Stick to lowercase words separated by hyphens, e.g. `feature/async-runner-hooks`.
|
||||
|
||||
---
|
||||
|
||||
## Step 4. Test Your Changes
|
||||
|
||||
Most updates should ship with automated checks. Preface commands with `uv run` so they use the project environment.
|
||||
|
||||
**Full test suite**
|
||||
|
||||
```bash
|
||||
uv run pytest -v
|
||||
```
|
||||
|
||||
**Targeted tests**
|
||||
|
||||
```bash
|
||||
uv run pytest tests/path/to/test_file.py -k test_name
|
||||
```
|
||||
|
||||
**Optional/gated tests**
|
||||
|
||||
GPU-specific suites or API-dependent tests run automatically when the required hardware or environment variables (such as `OPENAI_API_KEY`) are present.
|
||||
|
||||
**Static analysis**
|
||||
|
||||
```bash
|
||||
uv run pyright
|
||||
```
|
||||
|
||||
Touching code under `examples/`? Each directory includes a README with example-specific smoke tests—run those too.
|
||||
|
||||
---
|
||||
|
||||
## Step 5. Build Documentation (When Applicable)
|
||||
|
||||
Doc changes should build cleanly before you push:
|
||||
|
||||
```bash
|
||||
uv run mkdocs serve --strict # live reload while editing
|
||||
uv run mkdocs build --strict # CI-equivalent validation
|
||||
```
|
||||
|
||||
`--strict` matches CI and promotes warnings to errors so you catch them early.
|
||||
|
||||
---
|
||||
|
||||
## Step 6. Final Local Checks
|
||||
|
||||
- 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/<name>/README`.
|
||||
|
||||
---
|
||||
|
||||
## Step 7. Open a Pull Request
|
||||
|
||||
1. Push your branch to your fork:
|
||||
```bash
|
||||
git push origin <branch-name>
|
||||
```
|
||||
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!
|
||||
@@ -0,0 +1,86 @@
|
||||
# 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:
|
||||
```bash
|
||||
uv lock --upgrade
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
@@ -124,6 +124,8 @@ nav:
|
||||
- Types: reference/types.md
|
||||
- Internal: reference/internal.md
|
||||
- Miscellaneous:
|
||||
- Contributing Guide: community/contributing.md
|
||||
- Maintainer Guide: community/maintainers.md
|
||||
- Changelog: changelog.md
|
||||
|
||||
extra_css:
|
||||
|
||||
Reference in New Issue
Block a user