Skip to content

Commit f8d707d

Browse files
committed
docs: add the release recovery runbook
1 parent 44d6daa commit f8d707d

2 files changed

Lines changed: 36 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,9 +208,8 @@ installs from the lockfile, runs `pnpm test`, and runs `npm publish`.
208208
with no warning.
209209
- Every pull request runs the same `pnpm test`, in `.github/workflows/ci.yml`.
210210

211-
Nothing is tagged, so a failed publish leaves nothing stranded. Fix forward and merge
212-
again. If a publish half-succeeded, npm refuses that version from then on, so bump to the
213-
next patch instead.
211+
Nothing is tagged, so a failed publish leaves nothing stranded. When a release run fails,
212+
follow [docs/RELEASING.md](docs/RELEASING.md).
214213

215214
### Bumping the schema version
216215

‎docs/RELEASING.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Releasing
2+
3+
A push to `main` publishes the `version` in `package.json`, after `pnpm test`, when npm does not list that version yet. Nothing is tagged. [Releases](../README.md#releases) in the README has the details.
4+
5+
## When a release run fails
6+
7+
A failed run leaves nothing stranded. `main` holds a version npm does not have, and the next release run tries it again.
8+
9+
| Cause | What to do |
10+
|---|---|
11+
| Something in the repository, such as a failing test | Fix it in a pull request and merge. The merge's run publishes. |
12+
| Something outside it: npm was down, or the trusted publisher on npmjs.com does not match and `npm publish` failed with `ENEEDAUTH` | Fix that, then re-run the most recent release run. |
13+
| npm lists the version although the run failed | Nothing. The publish went through, and the next run publishes nothing. |
14+
15+
Never re-run a release run expecting a different result when nothing outside the repository changed.
16+
17+
npm never accepts the same version twice, even after an unpublish, per its [unpublish policy](https://docs.npmjs.com/policies/unpublish). To replace a published version, bump to the next patch. An unpublished version needs the same bump. npm keeps refusing it, although `npm view` no longer lists it.
18+
19+
## Runs close together
20+
21+
Two version bumps merged close together can run in either order, because GitHub does not guarantee the order of waiting runs. When the lower version runs last, npm 12 refuses it with [`Cannot implicitly apply the "latest" tag`](https://github.com/npm/cli/blob/v12.0.2/lib/commands/publish.js#L185), as long as the higher version is neither deprecated nor a prerelease. Nothing needs doing, and that version number is skipped.
22+
23+
That refusal also needs the run to read the higher version from the registry. A run whose read misses it can publish the lower version instead, and move `latest` back to it. After two close bumps, check that `npm view @tibia.sh/tibiawiki-data dist-tags.latest` prints the higher version. If it does not, and the higher version is not deprecated, point `latest` at it, with `X.Y.Z` as the higher version:
24+
25+
```bash
26+
npm login
27+
npm dist-tag add @tibia.sh/tibiawiki-data@X.Y.Z latest
28+
```
29+
30+
A push right after a publish can also read a version list from before that publish. Its run then tries to publish the same version again, and fails when npm refuses a version it already has. Nothing needs doing. A later run reads the new list and publishes nothing.
31+
32+
## Schema bumps
33+
34+
A schema bump publishes one release by hand, outside this workflow. Follow [Bumping the schema version](../README.md#bumping-the-schema-version).

0 commit comments

Comments
 (0)