Skip to content

Commit 7ca954f

Browse files
authored
Merge pull request #2755 from lidge-jun/codex/release-train-roadmap
docs(devlog): plan the dev to preview to main release train
2 parents 7c333f3 + f7f07fd commit 7ca954f

6 files changed

Lines changed: 303 additions & 0 deletions

File tree

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# 260827 release train — dev 7c333f30e to published
2+
3+
Research and decisions for promoting `dev` to both published channels. Written before any
4+
branch moves, because a promotion that drops a real commit is not recoverable by rerunning it.
5+
6+
## Starting state, measured
7+
8+
| Thing | Value |
9+
| --- | --- |
10+
| `dev` | `7c333f30e`, 293 commits ahead of `main` |
11+
| `main` | `ec51e42d7`, `release: v2.33.0` |
12+
| `preview` | `678517f56`, `release: v2.33.0-preview.20260825` |
13+
| `package.json` on dev | `2.34.0` |
14+
| npm `latest` | `2.33.0` |
15+
| npm `preview` | `2.33.0-preview.20260825` |
16+
| package name | `@bitkyc08/opencodex` |
17+
18+
Both channels are a full release behind `dev`.
19+
20+
## The preview reconciliation question
21+
22+
`preview` is 2 commits *ahead* of `dev`, which on its face means promoting `dev` onto
23+
`preview` would discard work. It does not, and the reason is worth writing down rather than
24+
asserting.
25+
26+
The two commits are `cf762b1f5` (a `dev` merge) and `678517f56` (the version bump).
27+
`cf762b1f5` shows a 24-line change to `tests/api-usage.test.ts`, which looks like real
28+
content — and `git merge-base --is-ancestor cf762b1f5 origin/dev` answers **NO**, so it is
29+
genuinely not in `dev`'s history.
30+
31+
The resolution is that ancestry and content are different questions. Measuring content
32+
directly:
33+
34+
```
35+
git diff --stat origin/dev origin/preview -- tests/api-usage.test.ts # empty
36+
git diff $(git merge-base origin/dev origin/preview) origin/preview --name-only
37+
# -> package.json
38+
```
39+
40+
So since the merge-base (`e1fb67559`), the *only* file `preview` changes is `package.json`,
41+
and the only change is the version string. `cf762b1f5` is a merge whose second parent IS the
42+
merge-base, so the test change it displays arrived on `dev` through a different commit and is
43+
already present there. Nothing real is lost.
44+
45+
**Decision:** promote `dev` onto `preview` and let the release bump re-establish the version.
46+
The stale `2.33.0-preview.20260825` string is exactly what the bump is going to overwrite.
47+
48+
## Version numbers
49+
50+
The published scheme, read from the registry rather than assumed:
51+
`2.29.0-preview.20260821`, `2.30.0-preview.20260821`, `2.31.0-preview.20260822`,
52+
`2.32.0-preview.20260824`, `2.32.1-preview.20260825`, `2.33.0-preview.20260825`. So preview is
53+
`<version>-preview.<YYYYMMDD>` and stable is plain semver.
54+
55+
- preview target: **`2.34.0-preview.20260827`**
56+
- stable target: **`2.34.0`**
57+
58+
`2.34.0` is what `dev`'s `package.json` already reads (wp2 of the hardening unit moved it
59+
there), it is unused on npm (404) and unused as a git tag, and both targets move their
60+
channel forward past `2.33.0`, which is what `assertChannelVersionMovesForward` requires.
61+
62+
## Mechanics that constrain the plan
63+
64+
`main` and `preview` rulesets are `[deletion, non_fast_forward, pull_request]` with bypass
65+
actors `DeployKey = always` and `RepositoryRole 5 = pull_request`. Two consequences:
66+
67+
- Content promotion cannot be a push. It travels as a PR merged with `--admin`.
68+
- The release bump push *can* work, but only through the deploy key. `scripts/release.ts`
69+
reads `OCX_RELEASE_SSH_KEY`; the key at `~/.ssh/opencodex_release_ed25519` was confirmed to
70+
authenticate and to see both branches.
71+
72+
`scripts/release.ts` is the release authority and does the whole sequence: preflight
73+
(clean tree, `audit:high`, `tsc`, the CI-matching test grouping, `privacy:scan`), bump,
74+
commit, push, wait for **both** Cross-platform CI and Service lifecycle at the release sha,
75+
then dispatch `release.yml` with `version`, `tag`, `expected-sha`, `dry-run`.
76+
77+
`release.yml` requires `expected-sha` and defaults `dry-run=true`, so a dry run exercises the
78+
real release commit. Re-running with `--publish` is the documented second step and the script
79+
is written to be idempotent across it.
80+
81+
## Constraint that shapes execution
82+
83+
The preflight runs the full test suite locally, which this session is forbidden to do. That
84+
is not a reason to bypass the preflight — it is a reason to run the suite where it belongs
85+
(`ssh lidge` via `ocx-run` at the exact release sha) and to let the workflow gates be the
86+
binding check. The plan records how each phase satisfies the preflight's intent without
87+
running `bun run test` on this machine.
88+
## Amendment — two things the first pass got wrong or left open
89+
90+
### The preflight is not the binding gate (resolves the `020` open question)
91+
92+
`020` framed the local test suite as a problem to work around. Reading `release.yml`
93+
end to end shows the gates that actually bind are all server-side, and the script's local
94+
preflight duplicates them as a convenience:
95+
96+
| Gate | Where it lives |
97+
| --- | --- |
98+
| `expected-sha` matches the checked-out commit | `release.yml` "Verify dispatched SHA" |
99+
| version equals `package.json` | "Verify version matches package.json" |
100+
| branch/version/dist-tag agree (main=stable+latest, preview=prerelease+preview) | "Require successful Cross-platform CI" |
101+
| a **push-event** `ci.yml` run succeeded for this sha on this branch | same step — a PR run explicitly does not qualify |
102+
| Service lifecycle succeeded when service paths changed since the previous merged tag | same step |
103+
| `audit:high` | "Dependency audit" job step |
104+
| typecheck + build | `prepublishOnly`, run by `npm publish` |
105+
| tag/release do not already exist at another sha | "Preflight release metadata" |
106+
107+
The workflow also creates the git tag and the GitHub Release itself (`git tag` /
108+
`gh release create`), so nothing about tagging depends on the local script.
109+
110+
So the route is: bump and push the release commit, let the branch's own push-event CI run,
111+
then dispatch `release.yml` directly with `gh workflow run`. That is exactly what
112+
`scripts/release.ts` does at its end, minus the local suite. Recording it this way is not a
113+
shortcut around a gate; it is declining to run a *duplicate* of gates the workflow enforces
114+
anyway, on a machine that is not allowed to run them.
115+
116+
The suite still runs — on `ssh lidge` at the exact release sha, as every phase of the
117+
hardening unit did.
118+
119+
### `[WRONG BRANCH]` on promotion PRs is expected, and is how this repo has always released
120+
121+
`010` guessed that `enforce-target` would complain. It does more than complain:
122+
`ALLOWED_BASES = ["dev"]` (`enforce-pr-target.yml:254`), so a promotion PR gets a
123+
`wrong_base` failure AND has `[WRONG BRANCH] ` prepended to its title.
124+
125+
This is not a new problem to solve. Every promotion in this repository's history carries it:
126+
127+
```
128+
#2553 codex/promote-main-2330 -> main [WRONG BRANCH] merge dev into main for the v2.33.0 release
129+
#2507 dev -> main [WRONG BRANCH] release: promote dev into main for v2.32.1
130+
#2551 dev -> preview [WRONG BRANCH] merge dev into preview for the v2.33.0-preview...
131+
```
132+
133+
All merged. The gate has no promotion exemption and the maintainers evidently merge through
134+
it with admin rather than teaching it about release branches. Follow that precedent rather
135+
than inventing an exemption: the check failing on a promotion PR is a known false positive,
136+
and the merge is `--admin` regardless.
137+
138+
Worth stating plainly since it looks alarming in the checks list: on a promotion PR,
139+
`enforce-target` failing is the expected outcome, not a signal to stop.
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# 010 — promote dev content onto preview
2+
3+
## What changes
4+
5+
`preview` moves from `678517f56` to a merge carrying `dev`'s tree at `7c333f30e`.
6+
No file in the repository is edited by this phase; it is a branch move only.
7+
8+
## How
9+
10+
`preview` requires a pull request, so:
11+
12+
```
13+
gh pr create --base preview --head dev --title 'release: promote dev to preview' ...
14+
gh pr merge <n> --merge --admin
15+
```
16+
17+
A PR from `dev` directly rather than a `codex/` branch, because the content being promoted
18+
IS `dev` — an intermediate branch would add a commit that says nothing.
19+
20+
Note `enforce-target` rejects PRs that do not target `dev`. A promotion PR targets
21+
`preview` by definition, so expect that check to complain and confirm it is the
22+
promotion exemption rather than a real finding before overriding it.
23+
24+
## Acceptance
25+
26+
- `git diff --stat origin/dev origin/preview` shows only `package.json` (the stale version
27+
string) or nothing at all
28+
- the merge sha is recorded
29+
- no `src/` or `tests/` file differs between the two branches
30+
31+
## What would make this wrong
32+
33+
Promoting before confirming the reconciliation in `000`. That check is done: since the
34+
merge-base, `preview`'s only exclusive change is the version string.
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# 020 — publish the preview prerelease
2+
3+
## Target
4+
5+
`2.34.0-preview.20260827`, dist-tag `preview`.
6+
7+
## How
8+
9+
From a checkout on `preview`, with the deploy key exported:
10+
11+
```
12+
OCX_RELEASE_SSH_KEY=~/.ssh/opencodex_release_ed25519 \
13+
bun scripts/release.ts 2.34.0-preview.20260827 --tag preview
14+
```
15+
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`.
19+
20+
## The preflight problem, and how this phase satisfies it honestly
21+
22+
The preflight runs the suite locally, which is forbidden here. Do not edit the script to
23+
skip it. Instead:
24+
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`.
34+
35+
## Acceptance
36+
37+
- `npm view @bitkyc08/opencodex dist-tags` shows `preview = 2.34.0-preview.20260827`
38+
- `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
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 030 — promote dev content onto main
2+
3+
## What changes
4+
5+
`main` moves from `ec51e42d7` (293 commits behind) to a merge carrying `dev`'s tree.
6+
This is the promotion the readiness statement in `260827_dev_hardening/070` was written for.
7+
8+
## How
9+
10+
Same shape as `010`: a PR from `dev` to `main`, merged with `--admin`, because `main`
11+
requires a pull request and the `RepositoryRole` bypass is `pull_request` only.
12+
13+
## Ordering
14+
15+
After `020`, not before. Publishing the preview channel first is what makes the stable
16+
release a re-publication of already-exercised content rather than a first contact.
17+
18+
## Acceptance
19+
20+
- `git diff --stat origin/dev origin/main` shows only `package.json` or nothing
21+
- the merge sha is recorded
22+
- `main` contains `origin/dev` (`git merge-base --is-ancestor origin/dev origin/main`)
23+
24+
## Carried forward from the hardening unit
25+
26+
PR #2745 is unmerged by design, so the credential-identity drift it fixes ships to `main`
27+
unfixed. That is disclosed in the readiness statement and is not a new decision made here.
28+
The release notes must not imply otherwise.
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 040 — publish the stable release
2+
3+
## Target
4+
5+
`2.34.0`, dist-tag `latest`.
6+
7+
## How
8+
9+
From a checkout on `main`:
10+
11+
```
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
15+
```
16+
17+
`release.ts` refuses a prerelease version on `main`, so the plain `2.34.0` is required
18+
here rather than a matter of taste.
19+
20+
## Acceptance
21+
22+
- `npm view @bitkyc08/opencodex dist-tags` shows `latest = 2.34.0`
23+
- `npm view @bitkyc08/[email protected] gitHead` equals the `main` release commit
24+
- the `v2.34.0` git tag exists and points at that commit
25+
- the published tarball's `package.json` version reads `2.34.0` — checked by unpacking,
26+
not by trusting registry metadata
27+
28+
## Risk
29+
30+
npm publish is irreversible. The dry run is not optional ceremony: it is the only
31+
rehearsal available. Read the dry-run job log for the packed file list before publishing —
32+
a release that ships the wrong files cannot be unshipped, only superseded.
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 050 — docs deploy and installed-runtime proof
2+
3+
## Docs deploy
4+
5+
`deploy-docs.yml` triggers on push to `main` under `docs-site/**`. The `030` promotion
6+
carries 293 commits of `docs-site` changes, so the deploy should fire on that merge without
7+
a manual dispatch. Confirm rather than assume: if the path filter did not match, dispatch it.
8+
9+
## Installed-runtime proof
10+
11+
Registry metadata is not the same claim as a working install. Install the published
12+
version into a scratch prefix and run it:
13+
14+
```
15+
cd "$(mktemp -d)" && npm i @bitkyc08/[email protected] && npx ocx --version
16+
```
17+
18+
The version the runtime reports is the evidence, not what the registry says it stored.
19+
20+
## Release record
21+
22+
Write the outcome to this unit: both channel versions, both release commits, both workflow
23+
run ids, the docs deploy run id, and what was deliberately NOT included (#2745). Then the
24+
unit is closable to `_fin`.
25+
26+
## Acceptance
27+
28+
- the docs deploy run for the `main` release concluded `success`
29+
- a real install of `2.34.0` reports `2.34.0` from its own runtime
30+
- the record names every sha and run id rather than describing them

0 commit comments

Comments
 (0)