Problem
Currently, the release version must be manually determined (pnpm version patch/minor), requiring manual analysis of the commit history to decide the appropriate bump type. Since the project already follows Conventional Commits, this can be automated.
Current Release Flow
Manual decision: pnpm version patch|minor|major
→ git tag v0.4.x
→ git push origin v0.4.x
→ GitHub Actions (publish-npm.yml / release-vscode.yml) auto-deploy
Why release-please
| Tool |
Stars |
Automation |
Fit |
| semantic-release |
~23k |
Fully automatic |
Overkill for current scale |
| Changesets |
~11.6k |
Changeset files per change |
Extra manual step per PR |
| release-please |
~6.8k |
PR-based review workflow |
Best fit — matches current review-then-release process |
| Cocogitto |
~1k |
CLI cog bump |
Less GitHub integration |
Star history
Chosen: release-please — PR-based workflow (auto-generates Release PR → user reviews → merge triggers tag+release) aligns with project's manual review before publish pattern. Google-maintained, Apache-2.0.
Proposed Flow
Commits land on main (Conventional Commits)
→ release-please auto-creates/updates "Release PR"
(bumps version, updates CHANGELOG.md)
→ User reviews Release PR
→ Merge → release-please creates git tag + GitHub Release
→ Existing publish-npm.yml / release-vscode.yml triggered by tag
Monorepo Considerations
- release-please supports manifest mode for monorepos
- npm packages (core, web, mcp): grouped release via root
pnpm version
- vscode-extension: independent release cycle (
vscode-v* tags) — separate release-please config or excluded
Commit Type → Version Mapping
| Commit Type |
Bump |
feat |
minor |
fix, perf |
patch |
BREAKING CHANGE |
major |
docs, style, refactor, test, chore, ci |
none |
Checklist
Verification
- Merge a
feat: commit to main → Release PR appears with correct version bump and CHANGELOG
- Merge a
fix: commit → Release PR updates with patch bump
- Merge Release PR → git tag
v0.x.x created → publish-npm.yml triggers automatically
- Only
docs:/test: commits → no Release PR created
Note: PR #129 (manual commit counting approach) will be superseded by this migration.
Problem
Currently, the release version must be manually determined (
pnpm version patch/minor), requiring manual analysis of the commit history to decide the appropriate bump type. Since the project already follows Conventional Commits, this can be automated.Current Release Flow
Why release-please
cog bumpStar history
Chosen: release-please — PR-based workflow (auto-generates Release PR → user reviews → merge triggers tag+release) aligns with project's manual review before publish pattern. Google-maintained, Apache-2.0.
Proposed Flow
Monorepo Considerations
pnpm versionvscode-v*tags) — separate release-please config or excludedCommit Type → Version Mapping
featfix,perfBREAKING CHANGEdocs,style,refactor,test,chore,ciChecklist
release-please-config.jsonand.release-please-manifest.json.github/workflows/release-please.ymlworkflowpublish-npm.ymltag triggersuggest-version.yml(PR ci: add suggest-version workflow for automated version calculation #129)feat:commit → Release PR auto-created with minor bumpfeat!:commit (smoke test from PR ci: add suggest-version workflow for automated version calculation #129 review)bootstrap-sha/initial-versionfor first run before anyv*tag exists (from PR ci: add suggest-version workflow for automated version calculation #129 review)feat!:produces one entry per package (from PR ci: add suggest-version workflow for automated version calculation #129 review)Verification
feat:commit to main → Release PR appears with correct version bump and CHANGELOGfix:commit → Release PR updates with patch bumpv0.x.xcreated →publish-npm.ymltriggers automaticallydocs:/test:commits → no Release PR created