Skip to content

feat: migrate repo releases to manual release-please#293

Merged
tmchow merged 13 commits intomainfrom
feat/release-please-manual-releases
Mar 18, 2026
Merged

feat: migrate repo releases to manual release-please#293
tmchow merged 13 commits intomainfrom
feat/release-please-manual-releases

Conversation

@tmchow
Copy link
Copy Markdown
Collaborator

@tmchow tmchow commented Mar 18, 2026

Problem

Today the repo has one automated release path for the npm CLI, but the real release story is split across CI, manual maintainer workflows, stale docs, and multiple version surfaces.

That creates a few concrete problems:

  • every push to main is too close to a release, which makes batching awkward
  • multiple maintainers do not share one clear release process
  • plugin manifests, marketplace metadata, changelogs, and computed counts can drift out of sync
  • untouched plugins can get caught in repo-wide release pressure even when only one component changed
  • release authority is partly hidden in local maintainer workflows like release-docs

What This PR Solves

This PR moves the repo to a manual release-please model with one standing release PR for the whole repo.

After this lands:

  • merges can accumulate on main without immediately publishing anything
  • release timing becomes intentional: the release happens when the generated release PR is merged
  • component versioning becomes independent for cli, compound-engineering, coding-tutor, and marketplace
  • untouched components do not need version bumps
  • the root CHANGELOG.md remains the one canonical changelog
  • release-owned metadata, descriptions, and counts are handled by repo-owned scripts and CI instead of a local maintainer-only command

Resulting Release Process

The intended workflow after merge is:

  1. Normal feature PRs merge to main.
  2. The Release PR workflow updates one standing release PR for the repo.
  3. That release PR accumulates additional releasable merges until maintainers decide the batch is ready.
  4. Maintainers can use the manual Release Preview workflow to inspect what would release.
  5. The actual release happens only when the generated release PR is merged.
  6. npm publish runs only when the cli component is part of that release.

Example Scenarios

1. One merge lands, but we do not want to release yet

  • a fix: PR merges to main
  • the standing release PR updates
  • nothing is published yet
  • maintainers can wait for more work before cutting a release

2. More work lands before the release is cut

  • a later feat: PR merges to main
  • the same open release PR updates to include both changes
  • the pending version bump can increase based on the total unreleased work
  • maintainers still have not released anything until they merge the release PR

3. A plugin-only change ships without dragging unrelated components

  • a change lands only under plugins/coding-tutor/**
  • only coding-tutor should bump
  • compound-engineering, marketplace, and cli stay untouched
  • npm publish should not run unless cli is also part of that release

4. Marketplace changes stay marketplace-scoped

  • a new plugin is added to the catalog or marketplace metadata changes
  • marketplace bumps
  • existing plugin versions do not need to bump just because the catalog changed

5. An exceptional bump is needed

  • maintainers decide the inferred bump is too small
  • they use the preview/release override path instead of making fake commits
  • the release still goes through the same CI-owned process

What Changed

  • add release-please config and manifest for cli, compound-engineering, coding-tutor, and marketplace
  • add automatic release PR maintenance on main and a manual release preview workflow
  • move CLI npm publish into the release-please workflow path instead of publishing on every merge
  • retire .releaserc.json and .claude/commands/release-docs.md
  • centralize changelog ownership in the root CHANGELOG.md
  • add release component detection, metadata sync, root changelog rendering, and preview tooling under src/release/ and scripts/release/
  • update repo/plugin guidance so release-owned versions and changelog entries are automation-owned
  • make AGENTS.md canonical and reduce root CLAUDE.md to a compatibility shim
  • update the Kiro converter to prefer AGENTS.md with CLAUDE.md fallback

Verification

  • bun test
  • bun run release:validate
  • bun run release:preview --title 'fix: adjust ce:plan-beta wording' --file plugins/compound-engineering/skills/ce-plan-beta/SKILL.md
  • bun test tests/kiro-converter.test.ts

Pre-Merge Limitation

  • the Release Preview workflow is defined in this PR, but workflow_dispatch workflows may not appear in this repo's Actions UI until the workflow exists on main
  • pre-merge validation here is local/script-level validation, not full GitHub Actions proof of release-please behavior on the default branch

First Validation After Merge

  • validate the first live Release PR workflow run on main
  • inspect the generated release PR for correct component bumps, metadata updates, and root changelog behavior
  • confirm normal merges to main do not publish npm directly
  • confirm CLI publish only runs when the cli component is actually released

@tmchow tmchow merged commit f47f829 into main Mar 18, 2026
2 checks passed
This was referenced Mar 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant