open/repo-mailbox
1
0
Fork 0
Code Issues Releases 2 Activity

docs(release): correct two claims about release-plugin.mjs that no longer hold

Browse source 
Both were read off the catalog's release-plugin.mjs today rather than assumed
to have stayed still, while preparing the 0.28.0 release this file describes.
They are recorded rather than deleted because the old text told a release
session to expect a half-applied catalog and to hand-commit its way out of
one - advice that would now be acted on for a failure mode that cannot occur.

- "--create-tag creates AND pushes the tag even without --write" is false.
  shouldCreateTag() returns 'create' only under --write, 'dry-run' otherwise,
  and its own comment says it used to fire on the documented dry-run entry
  point. A dry run now publishes nothing.
- "Catalog is evaluating a pre-flight gate but it is not implemented yet" is
  false. It shipped: applyRelease() runs check-versions.mjs FIRST and returns
  BLOCKED before writing anything, so a red plugin can no longer leave
  marketplace.json written-but-uncommitted.

What is unchanged, and why the manual pre-flight is still worth running:
preflightErrors() collects ERROR from every plugin, not just the one being
released, so an unrelated plugin in ERROR still blocks the release - it just
blocks it cleanly now.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AZa4oEsa93ac6pZQFEXqBF
This commit is contained in:
Kjell Tore Guttormsen 2026-08-20 23:06:35 +02:00
commit 7fa2220963
1 changed files with 27 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

43
CLAUDE.md
View file

@ -908,24 +908,33 @@ the catalog's `scripts/release-plugin.mjs repo-mailbox` (tag + ref bump
together);
verify with `scripts/check-versions.mjs`. Never hand-edit a ref.
Two things that script does that its dry-run label does not suggest:
`--create-tag` creates AND pushes the tag even without `--write`, and its
closing verification gate runs `check-versions.mjs` over ALL plugins — one
unrelated plugin in ERROR aborts it with the catalog edit written but
uncommitted. When that happens, commit the catalog's `marketplace.json` +
`README.md` by hand and leave every other dirty file in that repo alone.
**Two claims this file carried until 2026-08-20 are now FALSE, and both were
corrected by reading `release-plugin.mjs`, not by assuming it had stayed
still.** They are recorded rather than deleted because the old text told a
release session to expect a half-applied catalog and to hand-commit its way
out of one — advice that would now be acted on for a failure mode that cannot
occur.
**`--write --commit` does NOT close this window (confirmed by catalog,
2026-08-10).** The gate (`check-versions.mjs`) runs via `execFileSync` before
the `--commit` conditional, so it throws on any plugin's ERROR — including one
we did not touch — after the catalog files are written and before commit,
regardless of whether `--commit` was passed. Catalog is evaluating a
pre-flight gate (run the check before writing, abort there) but it is **not
implemented yet** — do not assume it exists. Until it ships: before running
`--write`, run `node scripts/check-versions.mjs` in the catalog manually and
confirm 0 ERROR first, even when the only ERROR belongs to an unrelated
plugin. If it still fires mid-release, fall back to the manual-commit
recovery above.
- *"`--create-tag` creates AND pushes the tag even without `--write`."* No
longer true. `shouldCreateTag()` returns `create` only when `args.write` is
set, `dry-run` otherwise, and the comment above it says in as many words
that it used to fire on the documented dry-run entry point. A dry run now
publishes nothing.
- *"Catalog is evaluating a pre-flight gate … but it is **not implemented
yet**."* It shipped. `applyRelease()` runs `check-versions.mjs` FIRST and
returns `BLOCKED` before writing anything, so a red plugin can no longer
leave `marketplace.json` written-but-uncommitted. The manual-commit recovery
the old text prescribed has nothing left to recover.
What is UNCHANGED, and is the reason the manual pre-flight is still worth
running: `preflightErrors()` collects ERROR from **every** plugin, not just
the one being released, so an unrelated plugin in ERROR still blocks the
release — it just blocks it cleanly now. Run `node scripts/check-versions.mjs`
in the catalog and confirm 0 ERROR before `--write`, so the block is something
you chose to look at rather than something the release run reports at you.
`--create-tag` is deliberately NOT gated on that catalog-wide check (its
preconditions are all local to the plugin), which is why the tag can be
correct while the catalog write is blocked.
## Hardening roadmap