diff --git a/docs/solutions/plugin-versioning-requirements.md b/docs/solutions/plugin-versioning-requirements.md index 12b9c64..73feb5e 100644 --- a/docs/solutions/plugin-versioning-requirements.md +++ b/docs/solutions/plugin-versioning-requirements.md @@ -3,6 +3,7 @@ title: Plugin Versioning and Documentation Requirements category: workflow tags: [versioning, changelog, readme, plugin, documentation] created: 2025-11-24 +date: 2026-03-17 severity: process component: plugin-development --- @@ -13,7 +14,13 @@ component: plugin-development When making changes to the compound-engineering plugin, documentation can get out of sync with the actual components (agents, commands, skills). This leads to confusion about what's included in each version and makes it difficult to track changes over time. -This document applies to release-owned plugin metadata and changelog surfaces, not ordinary feature work. The repo now treats `cli`, `compound-engineering`, `coding-tutor`, and `marketplace` as separate release components prepared by release automation. +This document applies to release-owned plugin metadata and changelog surfaces for the `compound-engineering` plugin, not ordinary feature work. + +The broader repo-level release model now lives in: + +- `docs/solutions/workflow/manual-release-please-and-centralized-changelog.md` + +That doc covers the standing release PR, component ownership across `cli`, `compound-engineering`, `coding-tutor`, and `marketplace`, and the canonical root changelog model. This document stays narrower: it is the plugin-scoped reminder for contributors changing `plugins/compound-engineering/**`. ## Solution @@ -24,51 +31,54 @@ Embedded plugin versions are release-owned metadata. Release automation prepares Contributors should: 1. **Avoid release bookkeeping in normal PRs** - - Do not manually bump `.claude-plugin/plugin.json` - - Do not manually bump `.claude-plugin/marketplace.json` + - Do not manually bump `plugins/compound-engineering/.claude-plugin/plugin.json` + - Do not manually bump the `compound-engineering` entry in `.claude-plugin/marketplace.json` - Do not cut release sections in the root `CHANGELOG.md` 2. **Keep substantive docs accurate** - Verify component counts match actual files - Verify agent/command/skill tables are accurate - Update descriptions if functionality changed + - Run `bun run release:validate` when plugin inventories or release-owned descriptions may have changed ## Checklist for Plugin Changes ```markdown Before committing changes to compound-engineering plugin: -- [ ] No manual version bump in `.claude-plugin/plugin.json` -- [ ] No manual version bump in `.claude-plugin/marketplace.json` +- [ ] No manual version bump in `plugins/compound-engineering/.claude-plugin/plugin.json` +- [ ] No manual version bump in the `compound-engineering` entry inside `.claude-plugin/marketplace.json` - [ ] No manual release section added to `CHANGELOG.md` - [ ] README.md component counts verified - [ ] README.md tables updated (if adding/removing/renaming) - [ ] plugin.json description updated (if component counts changed) +- [ ] `bun run release:validate` passes ``` ## File Locations -- Version is release-owned: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` +- Plugin version is release-owned: `plugins/compound-engineering/.claude-plugin/plugin.json` +- Marketplace entry is release-owned: `.claude-plugin/marketplace.json` - Changelog release sections are release-owned: root `CHANGELOG.md` -- Readme: `README.md` +- Readme: `plugins/compound-engineering/README.md` ## Example Workflow When adding a new agent: -1. Create the agent file in `agents/[category]/` -2. Update README agent table -3. Update README component count -4. Update plugin metadata description with new counts if needed -5. Leave version selection and release changelog generation to release automation +1. Create the agent file in `plugins/compound-engineering/agents/[category]/` +2. Update `plugins/compound-engineering/README.md` +3. Leave plugin version selection and canonical changelog generation to release automation +4. Run `bun run release:validate` ## Prevention -This documentation serves as a reminder. When Claude Code works on this plugin, it should: +This documentation serves as a reminder. When maintainers or agents work on this plugin, they should: 1. Check this doc before committing changes 2. Follow the checklist above 3. Do not guess release versions in feature PRs +4. Refer to the repo-level release learning when the question is about batching, release PR behavior, or multi-component ownership rather than plugin-only bookkeeping ## Related Files @@ -76,3 +86,4 @@ This documentation serves as a reminder. When Claude Code works on this plugin, - `plugins/compound-engineering/README.md` - `package.json` - `CHANGELOG.md` +- `docs/solutions/workflow/manual-release-please-and-centralized-changelog.md` diff --git a/docs/solutions/workflow/manual-release-please-and-centralized-changelog.md b/docs/solutions/workflow/manual-release-please-and-centralized-changelog.md new file mode 100644 index 0000000..0c22a2f --- /dev/null +++ b/docs/solutions/workflow/manual-release-please-and-centralized-changelog.md @@ -0,0 +1,178 @@ +--- +title: "Manual release-please migration for multi-component plugin and marketplace releases" +category: workflow +date: 2026-03-17 +created: 2026-03-17 +severity: process +component: release-automation +tags: + - release-please + - semantic-release + - changelog + - marketplace + - plugin-versioning + - ci + - automation + - release-process +--- + +# Manual release-please migration 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 changelog ownership + +That made it hard to batch merges on `main`, hard for multiple maintainers to share release responsibility, and easy for changelogs, plugin manifests, marketplace metadata, and computed counts to drift out of sync. + +## Root Cause + +Release intent, component ownership, changelog 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 four release components: + - `cli` + - `compound-engineering` + - `coding-tutor` + - `marketplace` +- Keep release timing manual: the actual release happens when the generated release PR is merged. +- Keep release PR maintenance automatic on pushes to `main`. +- Keep one canonical root `CHANGELOG.md`. +- Replace `release-docs` with repo-owned scripts for preview, metadata sync, validation, and root changelog rendering. +- 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. + +## Resulting Release Process + +After the migration: + +1. Normal feature PRs merge to `main`. +2. The `Release PR` workflow updates one standing release PR for the repo. +3. Additional releasable merges accumulate into that same release PR. +4. Maintainers can inspect the standing release PR or run the manual preview flow. +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. + +## 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` +- 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 + +## 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/render-root-changelog.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. +- Preserve one canonical root `CHANGELOG.md`. +- 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, metadata updates, and root changelog behavior. + +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 root `CHANGELOG.md` and release-owned metadata match the released components. + +## Related Docs + +- `docs/solutions/plugin-versioning-requirements.md` +- `docs/solutions/adding-converter-target-providers.md` +- `AGENTS.md` +- `plugins/compound-engineering/AGENTS.md` +- `docs/specs/kiro.md`