From d4ed02ba742495d110b1df31cd3c0563e69202f4 Mon Sep 17 00:00:00 2001 From: Drew Cain Date: Sat, 23 May 2026 14:00:01 -0500 Subject: [PATCH] docs(core): move release process from CONTRIBUTING.md to AGENTS.md (#846) Signed-off-by: Drew Cain Co-authored-by: Claude Opus 4.7 (1M context) --- AGENTS.md | 25 +++++++++++++++++++++++++ CONTRIBUTING.md | 34 ---------------------------------- 2 files changed, 25 insertions(+), 34 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 33f50c59..4dc3db72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -253,6 +253,31 @@ async_client.set_client_factory(your_custom_factory) See SPEC-16 for full context manager refactor details. +### Release Process + +Releases are driven by `just release` / `just beta` — never by a bare `git tag`. The recipes bump version metadata, run pre-flight checks, commit, tag, and push. GitHub Actions then publishes to PyPI and updates the Homebrew formula. + +**Stable release:** + +``` +just release v0.21.3 +``` + +The recipe runs `just lint` + `just typecheck`, then updates `__version__` in `src/basic_memory/__init__.py` and `"version"` in `server.json` (MCP registry metadata), commits as `chore: update version to X.Y.Z for vX.Y.Z release`, creates the `vX.Y.Z` tag, and pushes both the commit and the tag to `origin/main`. After the tag lands, the `Release` workflow builds the package, publishes to PyPI, creates the GitHub release with auto-generated notes, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover. + +**Beta release:** `just beta v0.21.3b1` — same flow with a beta-suffixed tag. PyPI consumers install with `pip install basic-memory --pre`. + +**Development builds:** every commit to `main` publishes a `0.21.3.dev26+468a22f`-style version to PyPI automatically via `.github/workflows/dev-release.yml`. No human action. + +**Do not tag releases by hand.** A bare `git tag vX.Y.Z` skips the in-code version bump. Package metadata is still correct (uv-dynamic-versioning derives it from the git tag) but `basic-memory --version` reports the previous release, which is what happened with v0.21.2 → v0.21.3. + +**Post-release tasks** the recipe surfaces but doesn't run: +- `docs.basicmemory.com` — add notes to `src/pages/latest-releases.mdx` +- `basicmachines.co` — bump version in `src/components/sections/hero.tsx` +- MCP Registry — `mcp-publisher publish` from the repo root + +See `.claude/commands/release/release.md` (and `beta.md`, `release-check.md`, `changelog.md` alongside it) for the full release + post-release runbook, including the slash commands. + ## BASIC MEMORY PRODUCT USAGE ### Knowledge Structure diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4ba19fc..a9f927c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -224,40 +224,6 @@ See `test-int/BENCHMARKS.md` for detailed benchmark documentation. - **Fixtures**: Use async pytest fixtures for setup and teardown - **Markers**: Use `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests -## Release Process - -Basic Memory uses automatic versioning based on git tags with `uv-dynamic-versioning`. Here's how releases work: - -### Version Management -- **Development versions**: Automatically generated from git commits (e.g., `0.12.4.dev26+468a22f`) -- **Beta releases**: Created by tagging with beta suffixes (e.g., `git tag v0.13.0b1`) -- **Stable releases**: Created by tagging with version numbers (e.g., `git tag v0.13.0`) - -### Release Workflows - -#### Development Builds -- Automatically published to PyPI on every commit to `main` -- Version format: `0.12.4.dev26+468a22f` (base version + dev + commit count + hash) -- Users install with: `pip install basic-memory --pre --force-reinstall` - -#### Beta Releases -1. Create and push a beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1` -2. GitHub Actions automatically builds and publishes to PyPI -3. Users install with: `pip install basic-memory --pre` - -#### Stable Releases -1. Create and push a version tag: `git tag v0.13.0 && git push origin v0.13.0` -2. GitHub Actions automatically: - - Builds the package with version `0.13.0` - - Creates GitHub release with auto-generated notes - - Publishes to PyPI -3. Users install with: `pip install basic-memory` - -### For Contributors -- No manual version bumping required -- Versions are automatically derived from git tags -- Focus on code changes, not version management - ## Creating Issues If you're planning to work on something, please create an issue first to discuss the approach. Include: