Skip to content

Commit 1964f2b

Browse files
ushironokoclaude
andcommitted
docs: correct RELEASING bootstrap for @tskm/core rename
The manual bootstrap section described an approach that does not work: NPM_CONFIG_PROVENANCE=false cannot disable provenance because publishConfig.provenance:true overrides the env var. Replace it with the verified procedure — temporarily remove the provenance line, publish with NPM_CONFIG_OTP, then restore the guardrail — and fix the runtime package name (tskm -> @tskm/core), the publish order, and the provenance expectation (the manual bootstrap versions, including @tskm/compiler@0.0.2, all have no provenance; the first CI OIDC release carries it). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent f93bc15 commit 1964f2b

1 file changed

Lines changed: 41 additions & 13 deletions

File tree

docs/RELEASING.md

Lines changed: 41 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Releasing
22

3-
How `tskm`, `@tskm/compiler`, and `@tskm/vite` are published, and the one-time setup
3+
How `@tskm/core`, `@tskm/compiler`, and `@tskm/vite` are published, and the one-time setup
44
required before the automated pipeline can run.
55

66
Publishing is **CI-only** and **tokenless**: GitHub Actions publishes via npm OIDC
@@ -23,30 +23,55 @@ Do these once, in order, before the first automated release.
2323

2424
### 2. Own the `@tskm` scope
2525
- Create / confirm ownership of the `@tskm` scope (org or user scope) on npmjs.com.
26-
`@tskm/compiler` and `@tskm/vite` cannot be published otherwise.
26+
`@tskm/core`, `@tskm/compiler`, and `@tskm/vite` cannot be published otherwise.
2727

2828
### 3. Bootstrap publish (first version only)
2929
The npm Trusted Publisher UI requires a package to already exist before you can attach a
30-
trusted publisher to it. So publish `0.0.1` of each package **once**, manually, from your
31-
machine. This first version has **no provenance** (provenance needs the CI OIDC context)
32-
— that is expected and unavoidable.
30+
trusted publisher to it. So publish each package **once**, manually, from your machine.
31+
These bootstrap versions have **no provenance** (provenance needs the CI OIDC context) —
32+
that is expected and unavoidable.
33+
34+
`publishConfig.provenance: true` stays in every `package.json` as a **fail-closed
35+
guardrail**: a non-CI publish refuses to run. It is **not** overridable by an environment
36+
variable — `NPM_CONFIG_PROVENANCE=false` does **not** turn provenance off, because
37+
`publishConfig` wins over env. So the bootstrap temporarily *removes* the line instead of
38+
trying to override it, then restores it.
3339

3440
```sh
3541
npm login # issues a short-lived (~2h) session, prompts for your passkey
3642
bun install --frozen-lockfile --ignore-scripts
3743
bun run build
38-
# Reuses scripts/publish.ts: ordered (compiler → tskm → vite), rewrites @tskm/vite's
39-
# workspace:* dependency, and is idempotent. NPM_CONFIG_PROVENANCE=false is REQUIRED —
40-
# publishConfig.provenance is true, which would otherwise fail outside CI.
41-
NPM_CONFIG_PROVENANCE=false bun run release
44+
45+
# Temporarily drop the guardrail (env vars can't override publishConfig): delete the
46+
# `"provenance": true` line from each packages/*/package.json. Do NOT commit this.
47+
48+
# scripts/publish.ts publishes in dependency order (@tskm/compiler → @tskm/core →
49+
# @tskm/vite), rewrites @tskm/vite's workspace:* dependency to a concrete range, and is
50+
# idempotent (versions already on the registry are skipped). NPM_CONFIG_OTP is required
51+
# because the account is 2FA "auth-and-writes"; the env propagates to all three
52+
# `npm publish` calls. The TOTP window is ~30s — if a later publish fails with EOTP, just
53+
# re-run with a fresh code and the already-published packages are skipped.
54+
NPM_CONFIG_OTP=<6-digit> bun run release
55+
56+
# Restore the guardrail (leaves main untouched):
57+
git checkout -- packages/*/package.json
4258
```
4359

60+
> Right after a publish, `npm view <pkg>` may return E404 for up to a few minutes
61+
> (registry propagation lag) even though the publish succeeded — do not mistake it for a
62+
> failure. The authoritative idempotent check is `bun run release` itself, which reports
63+
> already-published versions as `skip (already on registry)`.
64+
65+
> An earlier `@tskm/compiler@0.0.1` was published before the runtime was renamed to
66+
> `@tskm/core` (it targets the never-published unscoped `tskm`); it is **deprecated**. The
67+
> current compiler bootstrap is `@tskm/compiler@0.0.2`.
68+
4469
### 4. Install the pkg.pr.new GitHub App (for preview releases)
4570
- Install <https://github.com/apps/pkg-pr-new> and scope it to **only** `ushironoko/tskm`.
4671
Without it, `preview.yml` cannot publish preview packages.
4772

4873
### 5. Configure the Trusted Publisher on npmjs.com (per package)
49-
For **each** of `tskm`, `@tskm/compiler`, `@tskm/vite`:
74+
For **each** of `@tskm/core`, `@tskm/compiler`, `@tskm/vite`:
5075
- Package → Settings → **Trusted Publisher** → GitHub Actions
5176
- Organization/owner: `ushironoko`
5277
- Repository: `tskm`
@@ -63,7 +88,8 @@ For **each** of `tskm`, `@tskm/compiler`, `@tskm/vite`:
6388
### 7. After the first successful OIDC release
6489
- For each package, enable **"Require two-factor authentication and disallow tokens"**
6590
(trusted publishing keeps working under this setting).
66-
- Revoke any granular token used for the bootstrap publish.
91+
- The bootstrap publishes with a one-time OTP, not a long-lived token, so there is nothing
92+
to revoke — just confirm no granular/classic token was created for it.
6793

6894
---
6995

@@ -83,13 +109,15 @@ For **each** of `tskm`, `@tskm/compiler`, `@tskm/vite`:
83109
- the `version` job's gate detects an unpublished version (`should_publish=true`);
84110
- the `publish` job starts and **waits for `release` Environment approval**;
85111
- once approved, it builds, runs `publint` / `attw` / the clean-room install smoke
86-
test, then publishes `compiler → tskm → vite` over OIDC with provenance.
112+
test, then publishes `@tskm/compiler → @tskm/core@tskm/vite` over OIDC with provenance.
87113

88114
4. **Verify** the green provenance badge on npmjs.com and:
89115
```sh
90116
npm audit signatures
91117
```
92-
Expected provenance: **`0.0.1` = none** (bootstrap), **`0.0.2`+ = present**.
118+
Expected provenance: the manually bootstrapped versions — `@tskm/core@0.0.1`,
119+
`@tskm/compiler@0.0.2`, `@tskm/vite@0.0.1` — all have **none**. The first CI OIDC
120+
release of each package (its next version) is the first to carry **provenance**.
93121

94122
## Preview releases
95123

0 commit comments

Comments
 (0)