Skip to content

Commit 80df093

Browse files
authored
Merge pull request lidge-jun#2762 from lidge-jun/codex/release-train-record-2340
docs(devlog): record the v2.34.0 release train outcome
2 parents 79ffa8c + 175d31f commit 80df093

4 files changed

Lines changed: 243 additions & 29 deletions

File tree

Lines changed: 87 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,104 @@
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.
27

38
## Target
49

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` |
624

7-
## How
25+
So the git steps are the script's alone, and the publish gates are the workflow's alone.
826

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:
1030

1131
```
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
1442
```
1543

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
1955

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.
2159

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`.
2464

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.
3469

3570
## Acceptance
3671

3772
- `npm view @bitkyc08/opencodex dist-tags` shows `preview = 2.34.0-preview.20260827`
3873
- `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.

‎devlog/_plan/260827_release_train/030_main_promote.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,53 @@ release a re-publication of already-exercised content rather than a first contac
2626
PR #2745 is unmerged by design, so the credential-identity drift it fixes ships to `main`
2727
unfixed. That is disclosed in the readiness statement and is not a new decision made here.
2828
The release notes must not imply otherwise.
29+
30+
## Outcome — promoted, and the plan changed on contact
31+
32+
`main` = `80fff9a7f47332a4445df2b26ea175053fa55b0b` (merge of PR #2760, branch
33+
`codex/promote-main-2340` at `e25b653a2`). `git diff origin/dev origin/main` is **empty** —
34+
not "only package.json", empty — and `main` now carries `2.34.0`.
35+
36+
### The stale-version pattern this page inherited is no longer legal
37+
38+
This page and `000` both planned to keep `main`'s `2.33.0` through the conflict, following
39+
#2553 and #2507, so that the release bump would land on its own `release: v2.34.0` commit.
40+
The first push of the branch (`8a0bd3f83`) did exactly that and CI failed it correctly:
41+
42+
```
43+
(fail) release version line > the in-tree version is never behind a released one
44+
```
45+
46+
in both `test 3/4` (job `98518314466`) and `macos` (job `98518314397`).
47+
48+
`tests/release-version-line.test.ts` arrived **in this very delta**. It compares
49+
`package.json` against the highest local release tag, and once `v2.34.0-preview.20260827`
50+
existed, `compareReleaseTags("v2.33.0", "v2.34.0-preview.20260827")` is `-1`. The stale line
51+
put the tree behind a published version — precisely the "merging into main resolves
52+
package.json to main's side and silently republishes" failure the test's own header
53+
describes. The precedent PRs predate the test; they were not wrong, they are superseded.
54+
55+
Resolved by rebuilding from `ec51e42d7` with the conflict taken to dev's side
56+
(`8a0bd3f83` → `e25b653a2`, force-with-lease).
57+
58+
### What that costs at the release step
59+
60+
`release.ts:568` skips the bump when `package.json` already matches the target, so
61+
`v2.34.0` will be tagged on the promotion merge commit rather than on a separate
62+
`release: v2.34.0` commit. Acceptable: `release.yml` creates the tag itself after a
63+
successful publish and validates `expected-sha` against the checked-out commit, so the tag
64+
still names exactly the audited tree. `040` proceeds against `80fff9a7f` directly.
65+
66+
### Gate accounting
67+
68+
| Check | Result |
69+
| --- | --- |
70+
| Cross-platform CI `33074009466` | success, zero failed jobs |
71+
| Service lifecycle `33074009519` | success |
72+
| PR hygiene `33074473195` | success after `suppression-approved` was re-applied |
73+
| `enforce-target` | `wrong_base`, expected for a promotion (`ALLOWED_BASES = ["dev"]`) |
74+
| CodeQL | 53 alerts, none introduced: `dev` already has 84 open (78 high), `main` 73, and the branch diff against `dev` is empty |
75+
76+
The force-push cleared `suppression-approved` and re-added `intake: hygiene-blocked`, which
77+
is worth knowing for the next promotion: the label has to be re-applied after **every**
78+
push, not just the first.

‎devlog/_plan/260827_release_train/040_stable_release.md‎

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,29 @@
44

55
`2.34.0`, dist-tag `latest`.
66

7-
## How
7+
## How — revised after the promotion
88

9-
From a checkout on `main`:
9+
There is no release commit to make. `main` is `80fff9a7f` and already carries `2.34.0`,
10+
because `030` had to resolve the promotion conflict to dev's side to satisfy
11+
`tests/release-version-line.test.ts`. `release.ts:568` would skip the bump for exactly this
12+
reason, so `80fff9a7f` **is** the release commit and the workflow tags it directly.
13+
14+
That removes the only step the hand route existed to perform, so `040` is a pure dispatch:
1015

1116
```
12-
OCX_RELEASE_SSH_KEY=~/.ssh/opencodex_release_ed25519 \
13-
bun scripts/release.ts 2.34.0 --tag latest # dry run
14-
# inspect, then re-run with --publish
17+
# wait for the push-event ci.yml AND service-lifecycle runs at 80fff9a7f
18+
gh workflow run release.yml --ref main \
19+
-f version=2.34.0 -f tag=latest \
20+
-f expected-sha=80fff9a7f47332a4445df2b26ea175053fa55b0b -f dry-run=true
21+
# inspect the packed file list, then re-dispatch with dry-run=false
1522
```
1623

24+
The promotion push started both required runs on `main` on its own, plus
25+
`deploy-docs.yml`, which is what `050` needs.
26+
1727
`release.ts` refuses a prerelease version on `main`, so the plain `2.34.0` is required
18-
here rather than a matter of taste.
28+
here rather than a matter of taste. The workflow enforces the same mapping server-side:
29+
`main` must publish a non-prerelease version with dist-tag `latest`.
1930

2031
## Acceptance
2132

@@ -30,3 +41,30 @@ here rather than a matter of taste.
3041
npm publish is irreversible. The dry run is not optional ceremony: it is the only
3142
rehearsal available. Read the dry-run job log for the packed file list before publishing —
3243
a release that ships the wrong files cannot be unshipped, only superseded.
44+
45+
## Outcome — shipped
46+
47+
`2.34.0` published from `main` at `80fff9a7f47332a4445df2b26ea175053fa55b0b`, which is the
48+
promotion merge itself: no separate `release: v2.34.0` commit exists, and none was
49+
possible, for the reason recorded in `030`.
50+
51+
| Gate | Evidence |
52+
| --- | --- |
53+
| push-event Cross-platform CI | run `33075147758`, success at `80fff9a7f` |
54+
| Service lifecycle | run `33075147219`, success |
55+
| Release dry run | run `33076185925`, success; packed `@bitkyc08/[email protected]`, 838 files, 9.3 MB, `gui/dist/index.html` present |
56+
| Release publish | run `33076348477`, success |
57+
58+
Both channels now current, and neither disturbed the other:
59+
60+
- `dist-tags` = `{ latest: 2.34.0, preview: 2.34.0-preview.20260827 }`
61+
- `gitHead` of `2.34.0` = `80fff9a7f47332a4445df2b26ea175053fa55b0b`
62+
- tag `v2.34.0` resolves to the same commit; GitHub Release exists with `prerelease=false`
63+
64+
Artifact proof, by unpacking rather than by registry metadata: `npm pack`ed the published
65+
version into a `mktemp -d`, and `package/package.json` reads `2.34.0` with
66+
`package/gui/dist/index.html` present and both `bin` entries intact. Installing it into the
67+
same scratch directory and running the installed binary prints `opencodex 2.34.0`.
68+
69+
The dry-run packed size matched the preview's exactly (838 files, 9.3 MB, 19.9 MB unpacked),
70+
which is the expected result of publishing byte-identical trees to two channels.

‎devlog/_plan/260827_release_train/050_deploy_and_verify.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,65 @@ unit is closable to `_fin`.
2828
- the docs deploy run for the `main` release concluded `success`
2929
- a real install of `2.34.0` reports `2.34.0` from its own runtime
3030
- the record names every sha and run id rather than describing them
31+
32+
## Outcome — the release record
33+
34+
### Both channels, both commits
35+
36+
| Channel | Version | Release commit | Branch head |
37+
| --- | --- | --- | --- |
38+
| `preview` | `2.34.0-preview.20260827` | `809a06ba00340c905dfac4ab588616e638c2fbfd` | `origin/preview` |
39+
| `latest` | `2.34.0` | `80fff9a7f47332a4445df2b26ea175053fa55b0b` | `origin/main` |
40+
41+
`dev` stayed at `7ca954ffd997197d1cff6fc6d69842be51177a8f` throughout; both release trees are
42+
byte-identical to it apart from the preview's version string. `main` needed no separate
43+
release commit — the promotion merge is the release commit, for the reason in `030`.
44+
45+
### Run ids
46+
47+
| What | Run |
48+
| --- | --- |
49+
| preview push CI | `33072435012` |
50+
| preview service lifecycle | `33072435013` |
51+
| preview release dry run | `33073378226` |
52+
| preview release publish | `33073503058` |
53+
| promotion branch CI (the one that caught the version-line regression) | `33074009466` |
54+
| promotion branch hygiene (after relabel) | `33074473195` |
55+
| main push CI | `33075147758` |
56+
| main service lifecycle | `33075147219` |
57+
| main release dry run | `33076185925` |
58+
| main release publish | `33076348477` |
59+
| docs deploy | `33075147234` |
60+
61+
Remote full suite: `pvsuite` on `ssh lidge` at `62dfc6c54` (the tree both releases ship),
62+
15334 pass / 0 fail, rc=0.
63+
64+
### Docs deploy
65+
66+
`deploy-docs.yml` fired on the promotion push without a manual dispatch, as expected from
67+
the `docs-site/**` path filter. Run `33075147234` at `80fff9a7f`, both `build` and `deploy`
68+
jobs success, and the `github-pages` deployment `6123269073` is bound to that same sha.
69+
`https://opencodex.me/` answers `200` and serves the expected title. The legacy
70+
`/pages/builds/latest` API returns 404 here because Pages is workflow-built, not
71+
legacy-built — that is not a failure signal.
72+
73+
### Installed-runtime proof
74+
75+
In a `mktemp -d`: `npm pack @bitkyc08/[email protected]` then unpacked gives
76+
`package/package.json` at `2.34.0` with `package/gui/dist/index.html` present and both
77+
`bin` entries intact; installing it and running the installed binary prints
78+
`opencodex 2.34.0`. Packed size matched the preview exactly — 838 files, 9.3 MB packed,
79+
19.9 MB unpacked — which is what publishing identical trees to two channels should look
80+
like.
81+
82+
### What is deliberately NOT in this release
83+
84+
PR #2745 (OAuth 429 credential-identity rebind) is unmerged, awaiting the security review
85+
`MAINTAINERS.md` requires for credential-handling changes. The drift it fixes ships to both
86+
channels unfixed. This was disclosed in the readiness statement before the train started and
87+
is not a decision made here.
88+
89+
Separately, and worth stating plainly rather than burying: `dev` carries 84 open CodeQL
90+
alerts (78 high) against `main`'s previous 73, so this train raises the open-alert count by
91+
11. None were introduced by the promotion itself — the branch diff against `dev` was empty —
92+
but they now ship on `latest`. Triaging them is separate work against `dev`.

0 commit comments

Comments
 (0)