john/claude-engineering-plugin

Fork 0

Files

Trevin Chow 0e6c8e8221 docs: refresh stale target list and release component references (#339 )

2026-03-22 11:19:59 -07:00

8.2 KiB

Raw Blame History

title, category, date, created, severity, component, tags

title

Manual release-please with GitHub Releases for multi-component plugin and marketplace releases

Problem

The repo had one automated release path for the npm CLI, but the actual release model was fragmented across:

root-only semantic-release
a local maintainer workflow via release-docs
multiple version-bearing metadata files
inconsistent release-note ownership

That made it hard to batch merges on main, hard for multiple maintainers to share release responsibility, and easy for release notes, plugin manifests, marketplace metadata, and computed counts to drift out of sync.

Root Cause

Release intent, component ownership, release-note ownership, and metadata synchronization were split across different systems:

PRs merged to main were too close to an actual publish event
only the root CLI had a real CI-owned release path
plugin and marketplace releases depended on local knowledge and stale docs
the repo had multiple release surfaces (cli, compound-engineering, coding-tutor, marketplace) but no single release authority

An adjacent contributor-guidance problem made this worse: root CLAUDE.md had become a large, stale, partially duplicated instruction file, while AGENTS.md was the better canonical repo guidance surface.

Solution

Move the repo to a manual release-please model with one standing release PR and explicit component ownership.

Key decisions:

Use release-please manifest mode for five release components:
- cli
- compound-engineering
- coding-tutor
- marketplace (Claude marketplace, .claude-plugin/)
- cursor-marketplace (Cursor marketplace, .cursor-plugin/)
Keep release timing manual: the actual release happens when the generated release PR is merged.
Keep release PR maintenance automatic on pushes to main.
Use GitHub release PRs and GitHub Releases as the canonical release-notes surface for new releases.
Replace release-docs with repo-owned scripts for preview, metadata sync, and validation.
Keep PR title scopes optional; use file paths to determine affected components.
Make AGENTS.md canonical and reduce root CLAUDE.md to a compatibility shim.

Critical Constraint Discovered

release-please does not allow package changelog paths that traverse upward with ...

The failed first live run exposed this directly:

release-please failed: illegal pathing characters in path: plugins/compound-engineering/../../CHANGELOG.md

That means a multi-component repo cannot force subpackage release entries back into one shared root changelog file using changelog-path values like:

../../CHANGELOG.md
../CHANGELOG.md

The practical fix was:

set skip-changelog: true for all components in .github/release-please-config.json
treat GitHub Releases as the canonical release-notes surface
reduce CHANGELOG.md to a simple pointer file
add repo validation to catch illegal upward changelog paths before merge

Resulting Release Process

After the migration:

Normal feature PRs merge to main.
The Release PR workflow updates one standing release PR for the repo.
Additional releasable merges accumulate into that same release PR.
Maintainers can inspect the standing release PR or run the manual preview flow.
The actual release happens only when the generated release PR is merged.
npm publish runs only when the cli component is part of that release.
Component-specific release notes are published via GitHub releases such as cli-vX.Y.Z and compound-engineering-vX.Y.Z.

Component Rules

PR title determines release intent:
- feat => minor
- fix / perf / refactor / revert => patch
- ! => major
File paths determine component ownership:
- src/**, package.json, bun.lock, tests/cli.test.ts => cli
- plugins/compound-engineering/** => compound-engineering
- plugins/coding-tutor/** => coding-tutor
- .claude-plugin/marketplace.json => marketplace
- .cursor-plugin/marketplace.json => cursor-marketplace
Optional title scopes are advisory only.

This keeps titles simple while still letting the release system decide the correct component bump.

Examples

One merge lands, but no release is cut yet

A fix: PR merges to main
The standing release PR updates
Nothing is published yet

More work lands before release

A later feat: PR merges to main
The same open release PR updates to include both changes
The pending bump can increase based on total unreleased work

Plugin-only release

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

Marketplace-only release

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

Exceptional manual bump

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

Release Notes Model

Pending release state is visible in one standing release PR.
Published release history is canonical in GitHub Releases.
Component identity is carried by component-specific tags such as:
- cli-vX.Y.Z
- compound-engineering-vX.Y.Z
- coding-tutor-vX.Y.Z
- marketplace-vX.Y.Z
- cursor-marketplace-vX.Y.Z
Root CHANGELOG.md is only a pointer to GitHub Releases and is not the canonical source for new releases.

Key Files

.github/release-please-config.json
.github/.release-please-manifest.json
.github/workflows/release-pr.yml
.github/workflows/release-preview.yml
.github/workflows/ci.yml
src/release/components.ts
src/release/metadata.ts
scripts/release/preview.ts
scripts/release/sync-metadata.ts
scripts/release/validate.ts
AGENTS.md
CLAUDE.md

Prevention

Keep release authority in CI only.
Do not reintroduce local maintainer-only release flows or hand-managed version bumps.
Keep AGENTS.md canonical. If a tool still needs CLAUDE.md, use it only as a compatibility shim.
Do not try to force multi-component release notes back into one committed changelog file if the tool does not support it natively.
Validate .github/release-please-config.json in CI so unsupported changelog-path values fail before the workflow reaches GitHub Actions.
Run bun run release:validate whenever plugin inventories, release-owned descriptions, or marketplace entries may have changed.
Prefer maintained CI actions over custom validation when a generic concern does not need repo-specific logic.

Validation Checklist

Before merge:

Confirm PR title passes semantic validation.
Run bun test.
Run bun run release:validate.
Run bun run release:preview ... for representative changed files.

After merging release-system changes to main:

Verify exactly one standing release PR is created or updated.
Confirm ordinary merges to main do not publish npm directly.
Inspect the release PR for correct component selection, versions, and metadata updates.

Before merging a generated release PR:

Verify untouched components are unchanged.
Verify marketplace only bumps for marketplace-level changes.
Verify plugin-only changes do not imply cli unless src/ also changed.

After merging a generated release PR:

Confirm npm publish runs only when cli is part of the release.
Confirm no recursive follow-up release PR appears containing only generated churn.
Confirm the expected component GitHub releases were created and that release-owned metadata matches the released components.

docs/solutions/plugin-versioning-requirements.md
docs/solutions/adding-converter-target-providers.md
AGENTS.md
plugins/compound-engineering/AGENTS.md
docs/specs/kiro.md

8.2 KiB Raw Blame History