@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 +1 -1
- package/tools/colab +20 -11
- package/tools/lib/release-finalize.js +37 -9
package/package.json
CHANGED
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
|
|
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
|
|
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:
|
|
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
|
-
:
|
|
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
|
|
2164
|
-
//
|
|
2165
|
-
//
|
|
2166
|
-
|
|
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
|
-
&&
|
|
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
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
const
|
|
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,
|
|
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,
|
|
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) || (
|
|
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 (
|
|
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
|
}
|