The best way to control Claude Code, Codex and more from any computer or phone

main
md 92 lines 4.51 KB
Rendered Raw
1 # npm promote
2
3 `@effect/npm-promote` moves the `latest` dist-tag to a release that
4 `changeset publish` put under `staging`. It waits until npm's abbreviated
5 metadata lists the target version of every public workspace package, so fresh
6 installs never resolve an `@effect/*` version that needs an `effect` the
7 registry does not serve yet.
8
9 Preview what it would do from the repository root:
10
11 ```sh
12 node packages/tools/npm-promote/src/bin.ts --dry-run
13 ```
14
15 Each run:
16
17 1. Lists the non-private workspace packages and their versions at the
18 checked-out revision.
19 2. Fetches each package's abbreviated metadata from `registry.npmjs.org`. If any
20 target version is missing, nothing is promoted.
21 3. Runs `npm dist-tag add <name>@<version> latest`, `effect` first, for every
22 package whose `latest` is lower than the target. The CDN caches the
23 abbreviated metadata for minutes, so it only decides visibility; each
24 package is decided from its live `latest` on the dist-tags endpoint. A
25 higher `latest` is never moved back, so a run that failed halfway is
26 finished by the next one. A failed read or write stops the run, so no
27 package moves ahead of `effect`.
28 4. Deploys the website for the version bump commit when `effect`'s live
29 `latest` is exactly the target and no deploy is recorded for that commit.
30 Deploys are recorded as GitHub deployments in the `website-v4` environment,
31 so a failed or interrupted deploy is retried by the next run.
32 5. Closes every open tracking issue. A release that a newer one superseded
33 still closes them, and a failure to close never blocks the deploy.
34
35 When the version bump commit is older than `--overdue-after-hours` (12 by
36 default) and the release is still not visible or cannot be promoted, the tool
37 opens or updates a single tracking issue. For versions that are not visible it
38 checks each version's own registry document and lists versions missing from npm
39 (404), versions published but not visible yet, and versions whose check failed.
40 Failed `npm dist-tag add` writes are listed separately, and a registry read
41 that fails during promotion lists its version as unchecked. Read failures while
42 deciding the website deploy happen after promotion succeeded, so they fail the
43 run and are retried, but never open the tracking issue. Prerelease versions are
44 never promoted.
45
46 GitHub's issue listing can miss an open issue while GitHub is degraded, so a
47 run may open a duplicate tracking issue. The next run keeps the oldest open
48 tracking issue and closes the others as duplicates of it.
49
50 `--dry-run` reads the registry and prints the plan. It never moves dist-tags,
51 deploys the website, or touches GitHub issues. Real runs need
52 `GITHUB_REPOSITORY`, `GITHUB_TOKEN` and `WEBSITE_DISPATCH_TOKEN`.
53
54 ## Workflow
55
56 `.github/workflows/npm-promote.yml` runs every 10 minutes and after each
57 `Release` run on `main`. Setting the `NPM_PROMOTE_PAUSED` repository variable
58 to `true` skips new runs, which keeps a bad release on `staging`.
59
60 The job moves dist-tags with npm trusted publishing over OIDC, so no npm token
61 is stored anywhere. It runs in the `npm-promote` environment with
62 `id-token: write` and npm 11.21.0 or later. `effect` and every `@effect/*`
63 package need two trusted publisher configurations:
64
65 - `release.yml`: publishing allowed, "Allow npm dist-tag" off.
66 - `npm-promote.yml` in environment `npm-promote`: publishing not allowed,
67 "Allow npm dist-tag" on.
68
69 With no tokens involved, packages can also turn on "Require two-factor
70 authentication and disallow tokens".
71
72 ## Other writers of `latest`
73
74 Only this workflow is expected to move `latest`. `changeset publish` uses the
75 `staging` tag; npm sets `latest` itself only on the first publish of a new
76 package, which leaves it at the target. npm has no compare-and-set for
77 dist-tags, so the live read narrows but cannot close the window between reading
78 and writing a tag.
79
80 To change `latest` by hand, set `NPM_PROMOTE_PAUSED=true`, then wait until no
81 `npm promote` run is in progress: pausing only skips runs that have not started.
82 Unpause once the manual change is done. To roll back a bad release, stay paused
83 until `main` has a fixed version: once unpaused, the tool moves `latest` back
84 to the version at HEAD.
85
86 ## Website deploys
87
88 A deploy sends the `publish-api-reference` dispatch to Effect-TS/website. The
89 website builds an API reference snapshot keyed by the v3 and v4 revisions and
90 reuses it when that snapshot is already published, so a repeated dispatch for
91 the same revision only redeploys the site. A recorded deploy means the website
92 accepted the dispatch, not that its own deploy succeeded.