Skip to content

Commit 56734ad

Browse files
authored
docs: make the catalog refresh a release step, not an afterthought (#204)
* docs: make the catalog refresh a release step, not an afterthought The 0.1.4 release exposed a gap in the runbook rather than a one-off slip. `docs/RELEASING.md` describes packing the catalog `.zip` asset but never says to refresh the community-catalog entry that points at it, and nothing in the pipeline does it automatically — the entry is data in another repository, pinned to a specific release asset. The result: adrkit's entry sat at 0.1.2 through both 0.1.3 and 0.1.4, still advertising `speckit_version: >=0.13.0,<0.16.0` — a bound that by then refused to install on any current Spec Kit. Catalog users were getting a two-versions-old artifact whose manifest rejected their toolchain, while npm looked perfectly healthy. The npm publish looked like the whole release and was not. The mechanism also changed under us. Upstream's publishing guide now states plainly that pull requests against `catalog.community.json` are not accepted, and routes version bumps through the Extension Submission issue template. The original 0.1.0 listing did land as a PR (#3947), so the obvious move is now the wrong one and worth naming explicitly. - `docs/RELEASING.md` gains the refresh step in the adapter release section: file the issue (not a PR), wait for the asset to resolve because maintainers verify the URL, and change only `version`, `download_url`, `requires.speckit_version`, and `updated_at`. - ADR-0019 action item 5 records that this is a standing per-release obligation rather than the completed task it read as, and links the 0.1.4 refresh (github/spec-kit#4571). - The `[spec-kit-0.1.4]` CHANGELOG heading moves to 2026-09-13, the date the tag and release actually landed. The ADR and evidence-index dates are unchanged and correct — they date the re-verification, which did happen on 2026-09-12. Documentation only. Schema, `packages/ci`, and every shipped artifact untouched; `check:changelog`, `check:doc-pins`, `check:deps` and `adr lint` (37 records, 0 errors) pass. Claude-Session: https://claude.ai/code/session_01UHoVZxZp529qJg1mgwJqxZ Signed-off-by: Mark Beacom <[email protected]> * docs: correct the catalog history, scope the field list, stop calling a filing a refresh Review feedback on #204, all four points valid, and the factual one changes the story rather than just a detail. `github/spec-kit#3947` listed **0.1.2**, not 0.1.0 — and its body says "submitted by @mbeacom via issue #3942". Issue #3942 is ours, dated 2026-08-03 and labeled `extension-submission`; the pull request was the maintainer applying it the same day. So the contributor path was *always* the issue template. The previous text said the original listing "did land as a PR" and that "that path has since been closed", which implied a process change that never happened and invited exactly the pull request upstream refuses. Corrected to name both, and to say plainly that the pull request is the maintainer's step, not ours. That also dates ADR-0019's action item 5, which said "landed 2026-08-25"; the issue and the pull request are both 2026-08-03, corroborated by the catalog entry's own `created_at`. Corrected, with the prior claim noted rather than silently overwritten. The remaining three: - The `curl` check hardcoded `spec-kit-v0.1.4`. In a step whose whole point is that it recurs, copying it for 0.1.5 would validate the *old* asset and return 200 — confirming the wrong thing while looking like verification. Now binds `tag` once and interpolates it. - "Change only `version`, `download_url`, `requires.speckit_version`, and `updated_at`" was absolute where upstream asks for "any other changed fields". A future release that alters the description, `category`, `effect`, the command or hook counts, or `requires.tools` would have followed that instruction into a stale entry the version number does not reveal. Reframed as the common case, with the rule being to compare the proposed entry against `extension.yml`. - ADR-0019 called #4571 a completed refresh. It is an open submission: the entry is still 0.1.2, and `specify extension search` keeps serving it until a maintainer applies the update. Filing is not refreshing, and recording it as done would have hidden a live staleness behind a checked box — the same failure this PR exists to fix. Now recorded as submitted and open, with the refresh to be recorded when it lands. Documentation only. `check:changelog`, `check:doc-pins`, `check:deps`, and `adr lint` (37 records, 0 errors) pass. Claude-Session: https://claude.ai/code/session_01UHoVZxZp529qJg1mgwJqxZ Signed-off-by: Mark Beacom <[email protected]> --------- Signed-off-by: Mark Beacom <[email protected]>
1 parent c5cae1e commit 56734ad

3 files changed

Lines changed: 42 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Until `1.0.0`, minor releases may include breaking changes
99

1010
## [Unreleased]
1111

12-
## [spec-kit-0.1.4] - 2026-09-12
12+
## [spec-kit-0.1.4] - 2026-09-13
1313

1414
### Changed
1515

‎docs/RELEASING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,46 @@ where Spec Kit looks first. That zip is what a
202202
[`catalog.community.json`](https://github.com/github/spec-kit/blob/main/extensions/catalog.community.json)
203203
entry's `download_url` points at.
204204

205+
**Refresh that catalog entry as part of the release, not "later".** Nothing in
206+
the pipeline does it for you: the entry is data in someone else's repository,
207+
pinned to a specific release asset, and a release that skips this step leaves
208+
catalog users installing the *previous* artifact with the *previous*
209+
`speckit_version` bound. This is not hypothetical — the `adrkit` entry sat at
210+
0.1.2 through both the 0.1.3 and 0.1.4 releases, still advertising
211+
`>=0.13.0,<0.16.0`, which by then refused to install on any current Spec Kit.
212+
The npm publish looked like the whole release and was not.
213+
214+
The mechanism is an **issue, not a pull request** — and it always was. Upstream's
215+
[publishing guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md)
216+
is explicit — "Do **not** open a pull request directly to edit
217+
`extensions/catalog.community.json`" — and its "Updating an Existing Extension"
218+
section routes version bumps through the same
219+
[Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)
220+
template as a first listing, noting in the issue that it is an update. adrkit's
221+
own initial listing (at 0.1.2) followed exactly that path: issue
222+
[#3942](https://github.com/github/spec-kit/issues/3942), which a maintainer then
223+
applied in [#3947](https://github.com/github/spec-kit/pull/3947). That pull
224+
request is the maintainer's step, not ours — do not read it as a precedent for
225+
opening one. Wait until the release asset actually resolves, because maintainers
226+
verify the `download_url`, then file it:
227+
228+
```sh
229+
# The asset must return 200 before the entry is worth submitting.
230+
tag=spec-kit-v0.1.4 # the tag being released — not a copied constant
231+
curl -sIL -o /dev/null -w '%{http_code}\n' \
232+
"https://github.com/mbeacom/adrkit/releases/download/$tag/adrkit.zip"
233+
```
234+
235+
For a release that only moves the version and the pin, `version`,
236+
`download_url`, `requires.speckit_version`, and `updated_at` are the fields that
237+
change. That list is the common case, not a cap: upstream asks for "any other
238+
changed fields", so a release that alters the description, `category`, `effect`,
239+
the command or hook counts, or the `requires.tools` entries must carry those
240+
too, or the catalog goes stale in a way the version number does not reveal.
241+
Compare the proposed entry against `extension.yml` rather than against the
242+
previous entry. Only `created_at`, `verified`, `downloads`, and `stars` are
243+
maintainer-managed and preserved as listed.
244+
205245
`release-pack` validates **every** package's manifest regardless of scope — an
206246
adapter release is still a good moment to notice the lockstep surface drifted —
207247
but narrows what is packed, and requires the tag to match the adapter's own

‎docs/adr/0019-ship-the-spec-kit-extension-treating-the-spike-no-go-as-a-measurement-artifact.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ floating range that appears to work until it does not.
245245
2. [x] Enforce the read-only hook boundary with a test observed failing first
246246
3. [x] Re-verify the `speckit_version` pin against the next Spec Kit minor before widening it — done 2026-08-01, see the addendum above; widened to `<0.16.0`, verified at 0.13.0, 0.14.4, 0.15.1. **Superseded twice since, and this item records the practice rather than a one-time task:** re-verified 2026-09-09 and widened to `<1.1.0`, then extended 2026-09-12 to close the `1.0` line's upper edge. The current bound and its evidence live in the two addenda below, not on this line.
247247
4. [x] Decide whether to publish `@adrkit/spec-kit` to npm, or install it from the repository — **both channels**, see the addendum below
248-
5. [x] Submit the catalog entry to `github/spec-kit` once a release asset exists — landed 2026-08-25 via [github/spec-kit#3947](https://github.com/github/spec-kit/pull/3947); adrkit is listed in the community catalog
248+
5. [x] Submit the catalog entry to `github/spec-kit` once a release asset exists — submitted 2026-08-03 as issue [github/spec-kit#3942](https://github.com/github/spec-kit/issues/3942) and applied the same day by a maintainer in [#3947](https://github.com/github/spec-kit/pull/3947), listing version 0.1.2. (An earlier revision of this line said "landed 2026-08-25 via #3947"; both the issue and the pull request are dated 2026-08-03, and the pull request was the maintainer's step rather than ours.) **This is a standing per-release obligation, not a one-time task, and treating it as one-time cost two releases:** the entry stayed pinned at 0.1.2 through 0.1.3 and 0.1.4, still advertising `>=0.13.0,<0.16.0` — a bound that by then refused to install on any current Spec Kit. An update request for 0.1.4 was **submitted** 2026-09-13 as [github/spec-kit#4571](https://github.com/github/spec-kit/issues/4571) and is **still open**: the catalog entry remains at 0.1.2 until a maintainer applies it, so `specify extension search` keeps serving the stale entry in the meantime. Filing is not refreshing, and this item is not closed by the filing — record the refresh when the catalog change actually lands. The release runbook carries the step ([`docs/RELEASING.md`](../RELEASING.md)).
249249
6. [x] Remove `@adrkit/spec-kit` from `BOOTSTRAP_PACKAGES` after its first publish, once Trusted Publishing is configured for the name — done 2026-08-03; the set is now empty, which is its correct steady state. The `NPM_BOOTSTRAP_TOKEN` secret can be deleted.
250250

251251
### Addendum, 2026-08-02: distribution channels (action item 4)

0 commit comments

Comments
 (0)