|
1 | | -# 020 — publish the preview prerelease |
| 1 | +# 020 — publish the preview prerelease (revised) |
| 2 | + |
| 3 | +Supersedes the first draft of this page. The original said "invoke the script in a way that |
| 4 | +does not execute the suite here," which an independent audit of `scripts/release.ts` showed |
| 5 | +does not exist: the local suite at `scripts/release.ts:521-555` has no flag and no env |
| 6 | +escape, and the documented `--publish` re-entry re-runs it. |
2 | 7 |
|
3 | 8 | ## Target |
4 | 9 |
|
5 | | -`2.34.0-preview.20260827`, dist-tag `preview`. |
| 10 | +`2.34.0-preview.20260827`, dist-tag `preview`, from branch `preview` at the release commit. |
| 11 | + |
| 12 | +## Division of labour, measured rather than assumed |
| 13 | + |
| 14 | +`release.yml` never runs the test suite. What the script does that the workflow does not: |
| 15 | + |
| 16 | +| Step | Script | Workflow | |
| 17 | +| --- | --- | --- | |
| 18 | +| branch/clean-tree/version-shape preflight | yes | yes, later, against `GITHUB_REF` | |
| 19 | +| `assertUnusedReleaseVersion` + channel-moves-forward | both | unused-only | |
| 20 | +| `audit:high`, `tsc`, **full suite**, `privacy:scan` | yes | `audit:high` yes; suite **no**; `tsc`+GUI inside `prepublishOnly` | |
| 21 | +| bump, commit `release: v…`, deploy-key push | **yes** | **no** | |
| 22 | +| wait for push-event `ci.yml` + `service-lifecycle` at the sha | yes | requires the runs exist; does not wait | |
| 23 | +| create git tag + GitHub release | **no** | **yes**, and only when `dry-run != true` | |
6 | 24 |
|
7 | | -## How |
| 25 | +So the git steps are the script's alone, and the publish gates are the workflow's alone. |
8 | 26 |
|
9 | | -From a checkout on `preview`, with the deploy key exported: |
| 27 | +## Chosen route |
| 28 | + |
| 29 | +Run the git steps by hand, let the branch's own push-event CI run, then dispatch: |
10 | 30 |
|
11 | 31 | ``` |
12 | | -OCX_RELEASE_SSH_KEY=~/.ssh/opencodex_release_ed25519 \ |
13 | | - bun scripts/release.ts 2.34.0-preview.20260827 --tag preview |
| 32 | +# on preview, at the promoted head |
| 33 | +npm version 2.34.0-preview.20260827 --no-git-tag-version |
| 34 | +git commit -am 'release: v2.34.0-preview.20260827' |
| 35 | +GIT_SSH_COMMAND='ssh -i ~/.ssh/opencodex_release_ed25519 -o IdentitiesOnly=yes' \ |
| 36 | + git push [email protected]:lidge-jun/opencodex.git HEAD:preview |
| 37 | +# wait for push-event ci.yml AND service-lifecycle at that exact sha |
| 38 | +gh workflow run release.yml --ref preview \ |
| 39 | + -f version=2.34.0-preview.20260827 -f tag=preview \ |
| 40 | + -f expected-sha=<40-char sha> -f dry-run=true |
| 41 | +# inspect, then re-dispatch with dry-run=false |
14 | 42 | ``` |
15 | 43 |
|
16 | | -That is the dry run — `release.yml` defaults `dry-run=true`, and the script bumps, commits, |
17 | | -and pushes the real release commit either way. Inspect the dispatched run, then re-run the |
18 | | -same command with `--publish`. |
| 44 | +The suite runs on `ssh lidge` via `ocx-run` at that exact sha, as every phase of the |
| 45 | +hardening unit did. This is not skipping a gate: the suite is not one of `release.yml`'s |
| 46 | +gates, and the ones that are get enforced server-side regardless of what ran locally. |
| 47 | + |
| 48 | +Rejected alternative: running `bun scripts/release.ts` on lidge. It would work and it is |
| 49 | +the more faithful path, but it puts an interactive multi-stage release — including a |
| 50 | +20-minute CI wait and a deploy-key push — behind an ssh session, where a dropped |
| 51 | +connection strands a half-pushed release. The hand route makes each step separately |
| 52 | +observable and separately retryable. |
| 53 | + |
| 54 | +## Two traps, both verified in source |
19 | 55 |
|
20 | | -## The preflight problem, and how this phase satisfies it honestly |
| 56 | +**A dry run still pushes the bump.** `dry-run` only controls the workflow's publish/tag/ |
| 57 | +release steps (`release.yml:319-348`). The release commit is real either way, which is the |
| 58 | +point: the dry run exercises the actual commit. |
21 | 59 |
|
22 | | -The preflight runs the suite locally, which is forbidden here. Do not edit the script to |
23 | | -skip it. Instead: |
| 60 | +**`release.ts` skips the bump when the version already matches** (`release.ts:568`, |
| 61 | +`if (currentVersion === version)`). Harmless here, since `preview` carries `2.34.0` after |
| 62 | +the promotion and the target is the prerelease string. It matters for the stable release, |
| 63 | +where the target `2.34.0` equals what `dev` already carries — recorded in `040`. |
24 | 64 |
|
25 | | -1. Run the full suite on `ssh lidge` via `ocx-run` at the exact release sha first. |
26 | | -2. Let `release.ts` reach its test step. If it runs the suite locally, that violates the |
27 | | - constraint — so the suite step must be satisfied by the remote run and the script |
28 | | - invoked in a way that does not execute it here, or the release must be dispatched |
29 | | - directly via `gh workflow run release.yml` with the same `expected-sha` the script |
30 | | - would have used. |
31 | | -3. Whichever route is taken, record which gates actually ran and where. The binding |
32 | | - checks are the workflow's own: `release.yml` verifies the version matches |
33 | | - `package.json` and refuses if the branch moved off `expected-sha`. |
| 65 | +**Do not create the tag locally.** The `Protect release tags` ruleset (`20769150`) covers |
| 66 | +`refs/tags/v*` with `deletion`, `non_fast_forward`, and `update` and has no bypass actor, and |
| 67 | +`release.yml:268-274` refuses to publish a version whose tag already exists. The workflow |
| 68 | +creates the tag after a successful publish. |
34 | 69 |
|
35 | 70 | ## Acceptance |
36 | 71 |
|
37 | 72 | - `npm view @bitkyc08/opencodex dist-tags` shows `preview = 2.34.0-preview.20260827` |
38 | 73 | - `npm view @bitkyc08/[email protected] gitHead` equals the release commit |
39 | | -- the Release workflow run concluded `success` and was NOT a dry run |
40 | | -- Cross-platform CI and Service lifecycle were green at the release sha before dispatch |
| 74 | +- the Release run concluded `success` with `dry-run=false` |
| 75 | +- push-event Cross-platform CI and Service lifecycle were green at the release sha first |
| 76 | + |
| 77 | +## Outcome — shipped |
| 78 | + |
| 79 | +Release commit `809a06ba00340c905dfac4ab588616e638c2fbfd`, one file changed |
| 80 | +(`package.json`, 1 insertion 1 deletion), which is the same shape as both precedent |
| 81 | +release commits `ec51e42d7` (v2.33.0) and `678517f56` (v2.33.0-preview.20260825). Built in |
| 82 | +a detached worktree at `.tmp/rel-preview` so the `dev` checkout and the running local proxy |
| 83 | +were never touched, then pushed to `preview` with the deploy key. |
| 84 | + |
| 85 | +Gates, in the order the workflow demanded them: |
| 86 | + |
| 87 | +| Gate | Evidence | |
| 88 | +| --- | --- | |
| 89 | +| full suite at the promoted tree | `pvsuite` on `ssh lidge`, 15334 pass / 0 fail, rc=0, at `62dfc6c54` | |
| 90 | +| push-event Cross-platform CI | run `33072435012`, success at `809a06ba0` | |
| 91 | +| Service lifecycle | run `33072435013`, success at `809a06ba0` | |
| 92 | +| Release dry run | run `33073378226`, success; packed 838 files / 9.3 MB incl. a freshly built `gui/dist` | |
| 93 | +| Release publish | run `33073503058`, success | |
| 94 | + |
| 95 | +Registry and git metadata after the publish: |
| 96 | + |
| 97 | +- `dist-tags` = `{ preview: 2.34.0-preview.20260827, latest: 2.33.0 }` |
| 98 | +- `gitHead` of the published version = `809a06ba00340c905dfac4ab588616e638c2fbfd` |
| 99 | +- tag `v2.34.0-preview.20260827` resolves to the same commit; GitHub Release exists with |
| 100 | + `prerelease=true` |
| 101 | + |
| 102 | +The `gui/dist` question the audit raised answered itself in the dry run: the directory is |
| 103 | +gitignored but listed in `files`, and `prepublishOnly` builds it inside the workflow before |
| 104 | +`npm pack`, so the tarball carried `gui/dist/assets/index-BPGhccMP.js` and the rest. |
0 commit comments