Skip to content

RELEASING.md

Latest commit

 

History

History
60 lines (45 loc) · 2.24 KB

RELEASING.md

File metadata and controls

60 lines (45 loc) · 2.24 KB
Raw

Releasing

brainstack follows Semantic Versioning. The current version lives in VERSION; the history lives in CHANGELOG.md.

Version policy

  • MAJOR — breaking changes to the skill contract, the vault layout, or the bin/ CLI surface. Example: renaming a folder the setup script scaffolds.
  • MINOR — new capability that is backward compatible: a new skill, a new bin/ script, an additive change to a schema or template.
  • PATCH — fixes and documentation that change no contract.

Pre-1.0 (0.x): MINOR = breaking, PATCH = additive. We are at 1.0.0.

Release procedure

Run these steps in order. Each one is a separate commit so the history tells the story.

# 1. Bump the version
echo "1.1.0" > VERSION

# 2. Update CHANGELOG.md: move [Unreleased] into a dated section
#    ([1.1.0] - YYYY-MM-DD) following Keep a Changelog categories
#    (Added / Changed / Deprecated / Removed / Fixed / Security).

# 3. Commit the version bump
git add VERSION CHANGELOG.md
git commit -m "chore(release): v1.1.0"

# 4. Tag and push
git tag -a v1.1.0 -m "v1.1.0"
git push origin main --tags

# 5. Publish release notes (requires GitHub CLI)
gh release create v1.1.0 --title "v1.1.0" --notes "See CHANGELOG.md"

Verification before release

  1. python3 - <<'EOF' … run the frontmatter check from CONTRIBUTING.md — every skill must parse.
  2. bash setup --dry-run — installer must complete without errors.
  3. python3 -m py_compile bin/*.py — every engine script compiles.
  4. grep -c "name:" skills/*/SKILL.md — skill count matches the README table.
  5. If a template or schema changed, regenerate a scratch vault from vault-template/ and run bin/vault-health.py against it.

Rules of thumb

  • One concern per release. A docs fix is a PATCH; a new skill is a MINOR. Don't mix them in one tag.
  • The tag is the contract. Anyone can git checkout vX.Y.Z and get a coherent, working stack. If a tag doesn't reproduce, the release failed.
  • Every structural change gets a changelog entry. If it changes behavior, it is notable.
  • Breaking change → ARCHITECTURE.md and an ADR. A new constraint the stack enforces deserves a decision record, not just a diff.