@futurelastic/colab-handbook 1.13.0-rc.22 → 1.13.0-rc.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.22"
36
+ "version": "1.13.0-rc.23"
37
37
  }
package/tools/colab CHANGED
@@ -1851,7 +1851,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
1851
1851
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1852
1852
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
1853
1853
 
1854
- 1. fetches tags, picks the newest open candidate (never a hand-made or off-main one);
1854
+ 1. fetches tags, picks the newest open candidate — or the one --tag names (never a hand-made or
1855
+ off-main one);
1855
1856
  2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
1856
1857
  starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
1857
1858
  3. measures, and ends in exactly one state:
@@ -1884,7 +1885,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1884
1885
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1885
1886
  trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1886
1887
  another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1887
- none red — required only where the final is automatic
1888
+ none red — required only where the final is automatic, or for an older --tag (#548)
1888
1889
 
1889
1890
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
1890
1891
  the final equals every declared manifest version, its commit is on main (a shallow
@@ -1906,7 +1907,11 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1906
1907
  never tags: it stops at candidate-ready and posts the one command, number
1907
1908
  pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
1908
1909
  already-final exit 0 (nothing to do yet is the ordinary output)
1909
- --tag <rc> pin the candidate a human reviewed; refused unless it is the newest one
1910
+ --tag <rc> pin the candidate a human reviewed — the newest one, or any OLDER open candidate
1911
+ (#548). An older one is judged on its own clock exactly as --auto judges it: its
1912
+ own test period must have elapsed and trunk-green is read over its own window, on
1913
+ every row; release-hold and regressions as always. Newer candidates stay open
1914
+ for the next version — only versions below the final are closed as superseded
1910
1915
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
1911
1916
  No field, flag or project.yml value lowers it, and it never shortens a test period.
1912
1917
  Where the final is a human act the period is informational anyway, and
@@ -1982,6 +1987,8 @@ function cmdReleaseFinalize(argv) {
1982
1987
  const newest = selection.kind === 'candidate' ? selection.candidate : null;
1983
1988
  // #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
1984
1989
  const walk = opts.auto && policy.effective.final === 'auto' && newest;
1990
+ // #548: --tag naming an older open candidate — judged on its own clock, as the walk judges it.
1991
+ const ownClock = walk || (selection.kind === 'candidate' && !!selection.older);
1985
1992
 
1986
1993
  // ---- the tracking records (one issue read for the whole run) ----
1987
1994
  const issues = readAllIssuesForSwitches(repoAbs);
@@ -2040,7 +2047,7 @@ function cmdReleaseFinalize(argv) {
2040
2047
  return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
2041
2048
  }));
2042
2049
  const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
2043
- periodStart: period.start, periodEnd: walk ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2050
+ periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
2044
2051
  });
2045
2052
  const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
2046
2053
  const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
@@ -2119,7 +2126,7 @@ function cmdReleaseFinalize(argv) {
2119
2126
  const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2120
2127
  if (!opts.dry) {
2121
2128
  if (verdict.state === 'finalized') {
2122
- const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}`;
2129
+ const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2123
2130
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2124
2131
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2125
2132
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2143,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
2143
2150
  const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2144
2151
  comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
2145
2152
  ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — no test period on this repo (\`release.test-period: 0d\`, #549): the human's finalize is the test.`
2146
- : walk
2153
+ : ownClock
2147
2154
  ? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its own test period runs ${pNew.start} → ${pNew.endsAt}. A newer candidate does not restart an older one's clock: the newest candidate clean for its own period is finalized (\`--auto\`).`
2148
2155
  : `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
2149
2156
  }
@@ -2160,12 +2167,14 @@ function cmdReleaseFinalize(argv) {
2160
2167
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2161
2168
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2162
2169
  if (tagged) announced = announceRelease(cand.version, cand.sha);
2163
- // Superseded records. Without --auto: every other open, unheld, non-final version (the newest one
2164
- // is the only one ever finalized). With --auto: only versions BELOW one just tagged — a newer
2165
- // version's candidates are still on their own clocks.
2166
- if (cand && (!walk || tagged)) {
2170
+ // Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
2171
+ // without --auto closed every other open version at once, because only the newest candidate could
2172
+ // ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
2173
+ // to stay open until a final above it exists — closing it earlier refuses that --tag ("closed but
2174
+ // not final"). A newer version's candidates are still on their own clocks either way.
2175
+ if (cand && tagged) {
2167
2176
  for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
2168
- && (!walk || releaseFinalize.compareVersions(x.version, cand.version) < 0))) {
2177
+ && releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
2169
2178
  comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
2170
2179
  close(r.number);
2171
2180
  }
@@ -39,6 +39,12 @@
39
39
  * On a route whose final is a human act (`deploy-tag`) --auto never tags: it stops at
40
40
  * candidate-ready and posts the one command, number pre-filled.
41
41
  *
42
+ * `--tag` (#548) may name ANY open candidate, not only the newest, so a human can release what
43
+ * finished testing without trunk freezing for a whole period. An older one is held to the same rule
44
+ * --auto applies to it: its own test period and its own trunk window are required on every row
45
+ * (selectCandidate marks it `older`; decide() reads that). Newer candidates stay open, and a
46
+ * version's record closes as superseded only once a final ABOVE it is tagged.
47
+ *
42
48
  * Before ANY final, the three #424 pre-tag checks (release-tag.js preTagChecks) are required:
43
49
  * manifest-version, on-trunk, outranks-final.
44
50
  *
@@ -134,6 +140,8 @@ function trackingBody({ version, row, final, testPeriodDays }) {
134
140
  * { kind: 'already-final', version, detail }
135
141
  * { kind: 'refused', detail }
136
142
  * { kind: 'candidate', candidate: { tag, version, n, sha, cutAt }, superseded: [version], detail }
143
+ * { kind: 'candidate', older: true, newest: <tag>, … } #548: `pin` names an open candidate that
144
+ * is not the newest — decide() then requires its own test period and trunk window, as --auto does
137
145
  */
138
146
  function selectCandidate(tags, pin, remote = 'origin') {
139
147
  const all = tags || [];
@@ -159,16 +167,32 @@ function selectCandidate(tags, pin, remote = 'origin') {
159
167
  const newest = open[open.length - 1];
160
168
  const superseded = [...new Set(open.map((x) => x.p.version).filter((v) => v !== newest.p.version))];
161
169
 
162
- if (pin && pin !== newest.t.name) {
163
- return { kind: 'refused', detail: `--tag ${pin} is not the newest candidate (${newest.t.name}) — a final names the candidate that was actually tested last` };
164
- }
165
- const t = newest.t;
170
+ // #548: --tag may name an OLDER open candidate. It is then judged on its own clock, exactly as
171
+ // --auto judges it (decide() makes test-period and trunk-green over its own window required), so a
172
+ // human can release what finished testing while trunk keeps merging; the newer candidates stay open.
173
+ const chosen = pin ? open.find((x) => x.t.name === pin) : newest;
174
+ if (!chosen) return { kind: 'refused', detail: `--tag ${pin} is not an open candidate` };
175
+ const older = chosen !== newest;
176
+ const t = chosen.t;
166
177
  if (!t.annotated || !String(t.subject || '').endsWith(CUT_SUBJECT_SUFFIX)) {
167
178
  return { kind: 'refused', detail: `${t.name} was not made by \`colab release cut\` (not an annotated tag whose message ends "${CUT_SUBJECT_SUFFIX}") — a candidate cut by hand is never finalized (CONVENTIONS.md §6)` };
168
179
  }
169
180
  if (!t.onMain) return { kind: 'refused', detail: `${t.name} (${String(t.sha).slice(0, 7)}) is not on ${remote}/main — candidates are cut from main` };
170
181
  if (!t.date || Number.isNaN(Date.parse(t.date))) return { kind: 'refused', detail: `${t.name} has no readable tagger date — the test period cannot be placed` };
171
182
 
183
+ if (older) {
184
+ // Only versions BELOW the pinned one are superseded by it; a newer version's candidates stay open.
185
+ const below = [...new Set(open.map((x) => x.p.version).filter((v) => compareVersions(v, chosen.p.version) < 0))];
186
+ const newer = open.filter((x) => compareVersions(x.p.version, chosen.p.version) > 0 || (x.p.version === chosen.p.version && x.p.n > chosen.p.n)).map((x) => x.t.name);
187
+ return {
188
+ kind: 'candidate',
189
+ older: true,
190
+ newest: newest.t.name,
191
+ candidate: { tag: t.name, version: chosen.p.version, n: chosen.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
192
+ superseded: below,
193
+ detail: `${t.name} at ${String(t.sha).slice(0, 7)}, cut ${new Date(t.date).toISOString()} — an older candidate, judged on its own clock (newer, still open: ${newer.join(', ')})${below.length ? `; supersedes ${below.join(', ')}` : ''}`,
194
+ };
195
+ }
172
196
  return {
173
197
  kind: 'candidate',
174
198
  candidate: { tag: t.name, version: newest.p.version, n: newest.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
@@ -523,10 +547,14 @@ function decide(facts) {
523
547
  }
524
548
  const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
525
549
  add('regressions', reg.ok, reg.detail);
550
+ // #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
551
+ // --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
552
+ // no longer explains why THIS one, and its own clean period is what does.
553
+ const ownClock = auto || !!s.older;
526
554
  const per = f.period || { elapsed: false, detail: 'not measured' };
527
- add('test-period', per.elapsed, per.detail, auto);
555
+ add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
528
556
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
529
- add('trunk-green', tr.ok, tr.detail, auto);
557
+ add('trunk-green', tr.ok, tr.detail, ownClock);
530
558
  for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
531
559
  add(condition, v && v.ok, v ? v.detail : 'not measured');
532
560
  }
@@ -539,14 +567,14 @@ function decide(facts) {
539
567
  }
540
568
 
541
569
  if (held.length) return out('held');
542
- if ((reg.permanent) || (auto && tr.permanent)) return out('needs-new-candidate');
570
+ if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
543
571
  const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
544
572
  if (blocking.length) return out('refused');
545
- if (auto) {
573
+ if (ownClock) {
546
574
  if (!tr.ok && !tr.pending) return out('refused');
547
575
  if (!per.elapsed || tr.pending) return out('testing');
548
- return out('finalized', { finalTag: cand.version, grant: grantUsed });
549
576
  }
577
+ if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
550
578
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
551
579
  return out('finalized', { finalTag: cand.version });
552
580
  }