This project ships via the Node script at scripts/release-fix-workspace.ts. The script bumps versions, builds, publishes to npm, pushes tags, and creates a GitHub Release with notes from CHANGELOG.md.
Not every PR is a release. The typical workflow is:
- PRs → Merge features/fixes to
main(run mandatory checks below) - Accumulate → Multiple PRs can be merged before a release
- Release → When ready, run the release script to publish to npm
When to release:
- After significant features or bug fixes
- Before announcing to users
- When breaking changes need to be shipped
- Periodic releases (e.g., weekly/monthly)
These checks must pass before merging. If any fail, STOP and fix the issue.
pnpm lintCriteria: Zero errors. Warnings are acceptable but should be minimized.
pnpm -C packages/sdk build
pnpm -C packages/cli buildCriteria: Build completes successfully with no TypeScript errors.
pnpm testCriteria: 100% of tests pass (skipped tests are acceptable if documented).
pnpm test 2>&1 | grep -E "(% Stmts|All files)"Criteria:
| Package | Minimum Statements | Minimum Branches |
|---|---|---|
| SDK | 70% | 70% |
| CLI | 75% | 60% |
Note: Some areas have lower coverage due to entry points, worker-specific code, and external dependencies. Target 80%+ for core business logic.
All changes must be documented:
/CHANGELOG.md(root - user-facing)/packages/cli/CHANGELOG.md/packages/sdk/CHANGELOG.md
❌ Any linting errors
❌ Any TypeScript compilation errors
❌ Any failing tests
❌ Coverage below thresholds
❌ Missing changelog entries
- Node 18+
- pnpm (
corepack enable && corepack prepare pnpm@latest --activateworks too) - GitHub CLI (
gh auth statusshows logged in) - npm auth:
npm whoamiworks; 2FA ready if enabled - Clean
mainbranch pushed to origin
- Ensure all PRs are merged to
main - Update
CHANGELOG.mdwith a new section (e.g.,## [2.0.4] - YYYY-MM-DD) - Ensure any user-facing docs (README, templates) are committed
Patch/minor/major bump and publish:
pnpm tsx scripts/release-fix-workspace.ts patch # or minor/majorThe script will:
- Build all packages sequentially (SDK first, then CLI and MCP)
- Bump versions in
packages/cli/package.jsonandpackages/sdk/package.json - Replace workspace dependencies with actual versions
- Create git commit
chore: release vX.Y.Zand tagvX.Y.Z - Publish packages to npm (
codefetchandcodefetch-sdk) - Push commit and tags to remote
- Create a GitHub Release with notes extracted from
CHANGELOG.md
Build and pack locally:
pnpm build
pnpm --filter codefetch pack
pnpm --filter codefetch-sdk packVerify after publish:
- npm pages render correctly for both
codefetchandcodefetch-sdk - Git tag
vX.Y.Zexists - GitHub Release exists with changelog notes
- Both packages are published to npm with correct versions
- The script automatically extracts release notes from
CHANGELOG.md - Make sure to update
CHANGELOG.mdbefore running the release script - The release notes will include all items under the version heading (e.g.,
## 2.0.4)
To ship a prerelease:
pnpm tsx scripts/release-fix-workspace.ts patch --alphaThis creates an alpha version (e.g., 2.0.3-alpha.0) and publishes with the alpha tag.
Prefer deprecation over unpublish:
npm deprecate codefetch@X.Y.Z "Reason…"
npm deprecate codefetch-sdk@X.Y.Z "Reason…"Only unpublish if necessary and allowed (within 72 hours):
npm unpublish codefetch@X.Y.Z --force
npm unpublish codefetch-sdk@X.Y.Z --forceDelete the GitHub Release if needed: gh release delete vX.Y.Z
npm ERR! code E403or auth failures: runnpm loginand retryghfailures:gh auth status; ensurereposcope exists- Tag push rejected: pull/rebase or fast-forward
main, then rerun - CI fails with
ERR_PNPM_OUTDATED_LOCKFILE: The lockfile is out of sync withpackage.json. This happens when dependencies change (e.g.,workspace:*→^2.1.0). Fix it locally:pnpm install --no-frozen-lockfile git add pnpm-lock.yaml git commit -m "chore: update pnpm-lock.yaml" git push
- Patch releases (bug fixes): As needed
- Minor releases (features): Weekly or bi-weekly
- Major releases (breaking): Planned milestones