Releasing AgentFarm

This guide is for maintainers cutting a new release. Contributors should target dev; see CONTRIBUTING.md.

Overview

AgentFarm uses Semantic Versioning while the project is in active development:

While on 0.x, breaking changes are allowed but must be documented under a ### Breaking heading in CHANGELOG.md.

Branches:

• dev — integration branch for all contributor PRs
• main — stable release branch; updated only via maintainer release PRs

Release cadence

Choose one approach and stick to it so contributors know what to expect:

• Milestone-based (recommended today): cut a release when a feature set or research milestone is ready.
• Time-based: e.g. every 2–4 weeks once contributor velocity is steady.

Track planned work with GitHub Milestones named after the target version (0.2.0, etc.).

Each release should have a scope document under docs/milestones/ (for example 0.2.0.md). Create the GitHub milestone with Actions → Create release milestone (.github/workflows/create-release-milestone.yml) or locally:

gh workflow run create-release-milestone.yml \
  -f version=0.2.0 \
  -f assign_issues=954,944,930,952,953

Pre-release checklist

Before opening a release PR:

1. dev CI is green — the tests workflow must pass on the latest dev commit.
2. Heavy regressions — for releases touching simulation core, RL, or evolution code, confirm the nightly, deterministic-simulation, and evolution-regression workflows are green (run manually or wait for the latest scheduled run).
3. Changelog is ready — roll up recent dated entries into a version section (see below).
4. Version is bumped — update farm/_version.py (the single source of truth).

Step-by-step

1. Bump the version

Edit farm/_version.py:

__version__ = "0.2.0"

pyproject.toml reads this value automatically. Do not hard-code versions elsewhere.

Verify locally:

source venv/bin/activate
pip install -e .
python -c "from farm import __version__; print(__version__)"
python -c "from importlib.metadata import version; print(version('agentfarm'))"

Both commands must print the same version.

2. Update CHANGELOG.md

Add a version header above the dated entries:

## [0.2.0] - 2026-06-25

### Added
- ...

### Fixed
- ...

### Breaking
- ...

Keep the existing dated entries below for history, or consolidate them into the version section and remove duplicates.

The release workflow extracts notes from the ## [X.Y.Z] section using scripts/extract_release_notes.py.

3. Open a release PR (dev → main)

git checkout dev
git pull origin dev
git checkout -b release/0.2.0
# commit version + changelog changes
git push -u origin release/0.2.0

Open a PR from your release branch into main (not into dev). Title: Release v0.2.0.

The PR should contain only:

• farm/_version.py version bump
• CHANGELOG.md version section
• Any last-minute release-only doc tweaks

Get review, ensure CI passes, then merge to main.

4. Publish the GitHub Release

After the release PR merges to main:

1. Go to Actions → Release → Run workflow.
2. Enter the version without a leading v (e.g. 0.2.0).
3. Leave Publish to PyPI unchecked unless PyPI trusted publishing is configured (see below).

The workflow will:

• Verify farm/_version.py matches the input version
• Confirm the tag vX.Y.Z does not already exist
• Run the fast pytest suite (-m "not slow and not integration", excluding tests/test_deterministic_pytest.py)
• Build sdist and wheel artifacts
• Extract release notes from CHANGELOG.md
• Create tag vX.Y.Z and a GitHub Release with attached artifacts

5. Sync main back into dev

After releasing, merge main into dev so the version bump and changelog land on the integration branch:

git checkout dev
git pull origin dev
git merge origin/main
git push origin dev

Resolve conflicts if any, then delete the release branch.

6. Announce (optional)

For releases with user-visible changes (config schema, DB format, CLI):

• Post a short note in GitHub Discussions
• Link the GitHub Release and call out any ### Breaking items

Stability policy

Labels for contributors

Maintainers may use these GitHub labels when triaging:

PyPI publishing (optional)

Releases are distributed via GitHub Releases by default. To also publish to PyPI:

1. Create a PyPI project for agentfarm.
2. Configure trusted publishing for this repository’s release.yml workflow.
3. Re-run the release workflow with Publish to PyPI enabled.

Until then, users install from source or from release artifacts:

pip install git+https://github.com/Dooders/AgentFarm@v0.2.0
# or
pip install agentfarm-0.2.0-py3-none-any.whl

Troubleshooting

Related docs

• CONTRIBUTING.md — contributor workflow
• CHANGELOG.md — release notes source
• deployment.md — running AgentFarm in production