Skip to content

Commit 6c07502

Browse files
committed
docs(release): document npm dist-tag backfill hazard
Backfilling old GitHub Releases via npm publish can drag the `latest` dist-tag behind the real newest version, since npm assigns `latest` to whichever publish happens last, not the highest semver.
1 parent 004cbf0 commit 6c07502

2 files changed

Lines changed: 5 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ Full detail: [`prd.md`](.agents/docs/prd.md)
1818
- Feature work on `feat/*` branches off `develop`; merge to `develop`, then PR `develop → main` to release
1919
- All plans in `.agents/plans/<date>-<purpose>.md` before implementation begins
2020
- All work linked to a refined issue in [Project 14](https://github.com/users/espetro/projects/14/views/1)
21+
- Backfilling GitHub Releases must never trigger an npm publish — see [`CONTRIBUTING.md`](CONTRIBUTING.md#release-hygiene).

CONTRIBUTING.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ One logical change per commit. Keep commits independently revertable.
4040

4141
Community plugins live in separate repos (`agentplugins-<name>`) — not in this monorepo. They are ground-up rewrites, not mechanical ports. See the [plugin authoring guide](https://agentplugins.pages.dev/guide/creating-plugins).
4242

43+
## Release hygiene
44+
45+
When backfilling historical GitHub Releases, only use `gh release create <tag>` / edit release notes. Never re-run `pnpm release`, `changeset publish`, or `npm publish` against an old checked-out tag once a newer version is already live on the registry — npm's default `latest` dist-tag goes to whichever publish happens *last*, not whichever semver is highest, so a backfill publish silently drags `latest` backward.
46+
4347
## PR checklist
4448

4549
- [ ] `pnpm test` passes

0 commit comments

Comments
 (0)