Skip to content

Commit aac50fe

Browse files
committed
docs(devlog): record the v2.34.0 release train outcome
Fills in the outcome sections for the four release phases: the preview prerelease, the main promotion, the stable publish, and the deploy proof. Two plan pages had to change on contact rather than merely be annotated. 030 planned to keep main's stale 2.33.0 through the promotion conflict, following #2553 and #2507. CI failed that correctly: tests/release-version-line.test.ts arrived in this very delta and asserts the in-tree version is never behind the highest release tag, and once v2.34.0-preview.20260827 existed, 2.33.0 ordered behind it. The promotion was rebuilt to carry dev's 2.34.0, which makes the promotion merge itself the release commit. 040 therefore lost its only hand step. It is now a pure workflow dispatch against the promotion merge, since release.ts would skip the bump anyway. 050 carries the full record: every sha, every run id, the docs deploy and live-site proof, the unpacked-tarball and installed-binary proof, and the two disclosures - #2745 still unmerged pending security review, and the +11 open CodeQL alerts this train carries onto latest.
1 parent 7ca954f commit aac50fe

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)