Skip to content

Release Process

Jump to bottom
mvoutov edited this page May 12, 2026 · 4 revisions

Release Process

Step-by-step process for publishing a new version of aspens.

Important: everything required for the release must land in a PR before merge. Do not merge first and then patch release metadata on main. Version bumps, CHANGELOG.md, package.json metadata, lockfile updates, README/doc updates, and release-blocking fixes must all be in the release PR. Publish and tag only after that PR has merged and main matches what you intend to ship.

1. Make sure tests pass

cd aspens
npm test

Run a dry-run package build before publishing:

npm pack --dry-run

Check that src/, bin/, package.json, README.md are included and no secrets/junk sneak in.

2. Run CodeRabbit review

cr review --plain

Fix any findings before proceeding.

3. Bump version in package.json

Pick the right bump:

  • patch (0.2.0 → 0.2.1) — bug fixes, small improvements
  • minor (0.2.0 → 0.3.0) — new features
  • major (0.2.0 → 1.0.0) — breaking changes

Edit package.json version field directly, or:

npm version patch --no-git-tag-version
npm version minor --no-git-tag-version
npm version major --no-git-tag-version

4. Commit and push

git add -A
git commit -m "v0.2.1: description of changes"
git push origin your-branch

5. Create PR (if on a branch)

gh pr create --base main --title "v0.2.1: description" --body "## Summary
- change 1
- change 2

## Test plan
- [x] npm test passes
- [x] tested on a real repo
"

6. After PR merges — publish, tag, and release

git checkout main
git pull

Publish to npm

npm publish

If not logged in:

npm login
npm whoami    # verify
npm publish

Deprecate the previous version (if breaking or important fix)

npm deprecate aspens@<old-version> "Upgrade to <new-version> — <reason>. Run: npx aspens doc init --hooks-only after updating."

Tag and create the GitHub release

git tag v0.2.1
git push origin v0.2.1
gh release create v0.2.1 --title "v0.2.1 — <title>" --notes-file /dev/stdin

Release notes should cover: what's new, what's fixed, and upgrade steps for existing users.

7. Verify

npm view aspens
npx aspens@latest --version    # confirm the new version installs and runs
npx aspens@latest --help

8. Update docs

Check these for anything affected by the release:

  • README.md — commands table, options tables, examples
  • Wiki pages — clone aspenkit/aspens.wiki.git, update affected pages, push:
    • Architecture.md — project structure, data flow, new modules
    • How-Aspens-Works.md — pipeline description, doc sync, new command flows
    • Common-Recipes.md — new command recipes, new flags/options
    • Roadmap.md — move shipped items to completed
    • Release-Process.md — keep in sync with dev/release.md in the source repo
    • New features need new or updated wiki pages. If the release adds a command, flag, agent, or workflow, ensure there's a page (or section) covering it.
  • CLAUDE.md — quick reference, architecture section
cd /tmp && git clone https://github.com/aspenkit/aspens.wiki.git
# edit pages...
cd /tmp/aspens.wiki && git add -A && git commit -m "docs: update wiki for vX.Y.Z" && git push

9. Post an announcement

Use GitHub Discussions in the Announcements category. Cover:

  • what changed
  • why it matters
  • what existing users need to run after upgrading

Example:

gh api graphql -f query='mutation { createDiscussion(input: { repositoryId: "R_kgDORasXgA", categoryId: "DIC_kwDORasXgM4C45Q8", title: "aspens v0.8.0", body: "Highlights...\n\nUpgrade: run `aspens doc sync --refresh` in existing repos." }) { discussion { url } } }'

CodeRabbit commands

Run a review on uncommitted changes:

cr review --plain

In PR comments on GitHub:

  • @coderabbitai review — request a re-review
  • @coderabbitai resolve — mark a suggestion as resolved
  • @coderabbitai summary — regenerate the summary

Checklist

  • npm test passes
  • Version bumped in package.json
  • package.json fields reviewed (description, keywords, postinstall)
  • CHANGELOG.md updated
  • npm install run (lock file synced)
  • Committed + pushed to main
  • npm pack --dry-run looks clean
  • npm publish done
  • Old version deprecated (if needed)
  • Git tag created + pushed
  • GitHub release created with notes
  • GitHub Discussions announcement posted
  • Verified on npmjs.com + npx aspens@latest --version
  • README.md updated (if commands/options changed)
  • Wiki pages updated — new features have docs, existing pages reflect changes (Architecture, Recipes, Roadmap, etc.)

Quick reference

# Full release flow (after PR merges)
git checkout main && git pull
npm publish
git tag v0.2.1 && git push origin v0.2.1
gh release create v0.2.1 --title "v0.2.1" --generate-notes

Clone this wiki locally