diff --git a/AGENT.md b/AGENT.md index 4df72f1..b4289ff 100644 --- a/AGENT.md +++ b/AGENT.md @@ -99,100 +99,11 @@ ## Package Release Rules -Whenever releasing a new version of any package, ALWAYS follow this workflow. +Whenever releasing a new version of any package, ALWAYS follow the workflow in `Release_Guide.md`. -### 1. Validate the Project -- Ensure all tests pass. -- Ensure linting and formatting pass. -- Verify CI is green. -- Confirm the package builds successfully. -- Ensure documentation is up to date. +Quick reference: See `Release.md` for the release checklist. -### 2. Update the Release -- Update the package version following Semantic Versioning. -- Update CHANGELOG.md with all user-facing changes. -- Verify README examples and installation instructions. - -### 3. Commit Changes -- Create a release commit if needed. - -Commit message: - -``` -release: vX.Y.Z -``` - -### 4. Create Git Tag -- Create an annotated Git tag. - -Tag: - -``` -vX.Y.Z -``` - -Push the tag to GitHub. - -### 5. GitHub Release -Create a GitHub Release using the same tag. - -Release title should be descriptive. - -Example: - -``` -v0.5.0 – New Features & Improvements -``` - -Generate release notes with the following sections: - -- ✨ Features -- 🐛 Bug Fixes -- 📚 Documentation -- ⚙️ Internal Changes -- ❤️ Contributors - -Never use the version number alone as the release title. - -### 6. Automated Release -If GitHub Actions handles releases: - -- Wait for the workflow to finish. -- Verify build success. -- Verify package publishing succeeded. -- Verify GitHub Release was created. -- Stop immediately if any workflow fails. - -Never assume a release succeeded without verification. - -### 7. Post-Release Verification -Verify: - -- Git tag exists. -- GitHub Release exists. -- Package is available on the package registry. -- Fresh installation succeeds. -- The CLI/package reports the correct version. - -### 8. Final Report -After every release, provide a summary including: - -- Version released -- Release status -- CI status -- Package publish status -- GitHub Release status -- Any warnings or failures - -### Semantic Versioning - -| Change | Example | -|--------|---------| -| PATCH (bug fixes, docs, internal) | 0.4.5 → 0.4.6 | -| MINOR (backward-compatible features) | 0.4.5 → 0.5.0 | -| MAJOR (breaking changes) | 1.x.x → 2.0.0 | - -### Rules +Key rules: - Never skip tests. - Never skip CHANGELOG updates. - Never publish an unverified release. diff --git a/Release.md b/Release.md new file mode 100644 index 0000000..481cc80 --- /dev/null +++ b/Release.md @@ -0,0 +1,137 @@ +# Release Checklist + +Quick reference for releasing new versions of OpenAgent Eval. + +--- + +## Pre-Release + +- [ ] All tests pass (`pytest`) +- [ ] Linting passes (`ruff check .`) +- [ ] Formatting passes (`ruff format .`) +- [ ] CI is green +- [ ] Package builds successfully (`uv build`) +- [ ] Documentation is up to date + +--- + +## Update Version + +- [ ] Update `pyproject.toml` version +- [ ] Update `openagent_eval/__init__.py` version (must match) +- [ ] Update `CHANGELOG.md` with all changes since last release +- [ ] Update comparison links in CHANGELOG.md + +--- + +## Create Release Branch & PR + +```bash +git checkout main +git pull origin main +git checkout -b release/vX.Y.Z +git add pyproject.toml openagent_eval/__init__.py CHANGELOG.md uv.lock +git commit -m "chore: release vX.Y.Z" +git push -u origin release/vX.Y.Z +gh pr create --title "chore: release vX.Y.Z" --base main +``` + +- [ ] PR created and reviewed +- [ ] PR merged + +--- + +## Tag Release + +```bash +git checkout main +git pull origin main +git tag -a vX.Y.Z -m "Release vX.Y.Z" +git push origin vX.Y.Z +``` + +- [ ] Tag created and pushed + +--- + +## GitHub Release + +- [ ] GitHub Release created with descriptive title: `vX.Y.Z – [Title]` +- [ ] Release notes include PR links: `- **Name** — description (#PR_NUMBER)` +- [ ] Release notes include Contributors section + +--- + +## Post-Release Verification + +- [ ] Git tag exists (`git tag -l "vX.Y.Z"`) +- [ ] GitHub Release exists (`gh release view vX.Y.Z`) +- [ ] Package available on PyPI (`pip install openagent-eval==X.Y.Z`) +- [ ] CLI reports correct version (`oaeval --version`) +- [ ] CI workflow completed successfully + +--- + +## Semantic Versioning + +| Change | Example | +|--------|---------| +| PATCH (bug fixes, docs, internal) | 0.4.5 → 0.4.6 | +| MINOR (backward-compatible features) | 0.4.5 → 0.5.0 | +| MAJOR (breaking changes) | 1.x.x → 2.0.0 | + +--- + +## Release Notes Format + +```markdown +## What's Changed + +### ✨ Features +- **Feature Name** — description (#PR_NUMBER) + +### 🐛 Bug Fixes +- **Fix Name** — description (#PR_NUMBER) + +### 📚 Documentation +- **Doc Change** — description (#PR_NUMBER) + +### ⚙️ Testing +- **Test Change** — description (#PR_NUMBER) + +### ⚙️ Internal +- **Internal Change** — description (#PR_NUMBER) + +### ❤️ Contributors +- @contributor1 + +**Full Changelog**: https://github.com/openagenthq/openagent-eval/compare/vPREV...vX.Y.Z +``` + +--- + +## Files Involved + +| File | Purpose | +|------|---------| +| `pyproject.toml` | Canonical version | +| `openagent_eval/__init__.py` | Runtime version | +| `CHANGELOG.md` | Release history | +| `uv.lock` | Lock file | +| `.github/workflows/release.yml` | PyPI publish | + +--- + +## Troubleshooting + +### Version mismatch +Always update both `pyproject.toml` and `__init__.py` — they must match. + +### Push rejected +Use PR workflow — direct push to `main` is blocked. + +### Tag exists +```bash +git tag -d vX.Y.Z +git push origin :refs/tags/vX.Y.Z +```