Correct and expand the release instructions in CONTRIBUTING.md - #516
Correct and expand the release instructions in CONTRIBUTING.md#516jgfoster wants to merge 1 commit into
Conversation
Findings from cutting 1.8.11 through 1.8.14: - npm version also reformats package.json in npm's own JSON style, and format:check does not cover package.json, so the reformat would land in the release commit unnoticed. Document the restore. - ovsx refuses a duplicate rather than double-publishing; the message is "already published, but currently isn't active", not "already exists". The advice to re-run vsce directly stands, but for a different reason. - A CLI success message means the upload was accepted, not that the version is live; it takes ~2-22 minutes and either registry can lead. Add how to verify against each registry's API. - Step 5's .vsix is not the artifact that gets uploaded; both publish commands repackage into their own temp file. - Step 2 was narrower than the gate every PR is held to. - Note that a branch cut before the last Unreleased -> X.Y.Z rename lands its changelog bullet in the already-released section. Also documents ovsx login, verify-pat as a pre-flight, and the Azure PAT requirements (all accessible organizations + Marketplace > Manage). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
| # then edit package.json's "version" line by hand — it is the only occurrence of the old version | ||
| ``` | ||
|
|
||
| Then promote the `[Unreleased]` section in `CHANGELOG.md` to a new dated `[X.Y.Z]` heading. Sweep `main` since the last release for merged PRs that didn't add their own changelog entries — `git log --oneline vX.Y.Z..HEAD --merges --grep="Merge pull request"` lists them. **Check the previous release's section too:** a branch cut before the last `[Unreleased]` → `[X.Y.Z]` rename merges its bullet into that now-released section, so the entry claims to have shipped in a version that never contained it. Move any such entry into the new section. |
There was a problem hiding this comment.
💭 --merges --grep="Merge pull request" only finds PRs that landed as merge commits — a squash-merged PR and anything committed straight to main are both invisible to it. 7dc5233, the commit this PR re-applies, is exactly that second case, so the sweep would have missed it.
Would a plain git log --oneline vX.Y.Z..HEAD (or --no-merges) be safer here? Noisier, but the point of the sweep is to catch the entries nobody wrote down, and those are the likeliest to have arrived by an unusual route.
| 4. `git tag -a vX.Y.Z -m "Release X.Y.Z"` — annotated tag, on the release commit. | ||
| 5. `npx @vscode/vsce package` — produces `gemstone-ide-X.Y.Z.vsix` in the repo root. The previous version's `.vsix` is gitignored but stays on disk; delete it to keep the root tidy. | ||
| 6. `npm run publish` — runs `vsce publish` then `ovsx publish` for the VS Code Marketplace and Open VSX. If `vsce publish` times out on the Azure DevOps Gallery API (it happens), re-run `npx @vscode/vsce publish` directly — don't re-run `npm run publish`, since the ovsx step will then double-publish and fail with "already exists." | ||
| 5. `npx @vscode/vsce package` — produces `gemstone-ide-X.Y.Z.vsix` in the repo root. The previous version's `.vsix` is gitignored but stays on disk; delete it to keep the root tidy. Note this file is **not** what gets uploaded: both commands in step 6 repackage into their own temp `.vsix`. It is for local inspection and archival. |
There was a problem hiding this comment.
💭 There's an npm run package script (vsce package) and CLAUDE.md documents it as the packaging command — should this step use it, so the two don't drift?
| **`npm version` also reformats `package.json`.** It rewrites the whole file in npm's own JSON style, expanding the compact `devEngines` object and the `enum` arrays to one entry per line (~20 spurious lines). `npm run format` only globs `*.{ts,mts,cts,js,mjs,cjs}`, so **`format:check` will not catch this** and the reformat lands in the release commit. Undo it and change only the version line: | ||
|
|
||
| ```sh | ||
| npm version <X.Y.Z> --no-git-tag-version # updates package.json + package-lock.json | ||
| git checkout package.json # discard npm's reformat (the lockfile keeps its bump) | ||
| # then edit package.json's "version" line by hand — it is the only occurrence of the old version | ||
| ``` |
There was a problem hiding this comment.
🚫 I verified this claim, and it's problematic; I think we should remove it. At some point in the past, someone manually reformatted the package.json the wrong way, so the first time you attempted to create a release, npm fixed the formatting. But it seems you manually reverted that. The format should be the correct one in main right now, so these instructions are not really needed, but also are the wrong instructions. npm owns the format, so if it applies a reformat it will leave the file in the correct one.
2 participants
Findings from cutting 1.8.11 through 1.8.14 in one session. The mechanics in the existing section were right — steps 1, 3, 4, 5 and 7 behaved exactly as written — but six things were wrong or missing, and one of them would quietly corrupt a release commit.
Corrections
npm versionalso reformatspackage.json. It rewrites the file in npm's own JSON style, expanding the compactdevEnginesobject and theenumarrays to one entry per line (~20 spurious lines).npm run formatonly globs*.{ts,mts,cts,js,mjs,cjs}, soformat:checkdoes not catch it and the reformat lands in the release commit unnoticed. This happened on all four releases. Documents the restore sequence.npm run publishmakesovsx"double-publish and fail with 'already exists.'" Re-running it twice (1.8.11 and 1.8.13) showedovsxrefuses a duplicate rather than creating one, reportingalready published, but currently isn't active and therefore not visible. The advice to re-runvscedirectly stands; the stated reason did not..vsixis not the artifact that gets uploaded. Both publish commands repackage into their own temp file. Reading 5 → 6 in sequence implies otherwise.compile && testrather thanlint && format:check && compile && test.[Unreleased]→[X.Y.Z]rename merges its bullet into that released section, claiming it shipped in a version that never contained it. Explorer UX: filter icons and wording, filterable method categories, and honest class-comment affordances (#387) #442 did exactly this into[1.8.11]; caught and moved during 1.8.13.Additions
already published, but currently isn't activemeans wait, not retry — it resolved on its own both times. This cost a misdiagnosis during 1.8.11, where the ovsx step was wrongly assumed not to have run. Includes commands to verify against each registry's API rather than trusting CLI output.ovsx login, which was previously undocumented — the Open VSX half can be stored the same wayvsce loginstores the Marketplace half, so neither publish step needs anything in the environment.verify-patas a pre-flight for both registries, at the top of the section.All accessible organizations(a single-org token fails with a 401 that reads like a bad token) and scopeMarketplace → Manage. This is what stalled the first release of the session. Also notes that a lost PAT is replaced rather than recovered, and that an emptyvsce ls-publishersmeans no credentials on this machine rather than an unregistered publisher.Note on history
This change was first committed straight to
mainas 7dc5233, which skipped review. That commit has been reverted (cc666da) and re-applied here so it can go through the normal process. Net effect on merge is identical to 7dc5233.Docs-only — no build, extension, or CI surface.