@futurelastic/colab-handbook 1.15.0-rc.3 → 1.15.0-rc.5
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 +39 -16
- package/tools/lib/codec/release.d.ts +6 -3
- package/tools/lib/codec/release.js +16 -7
- package/tools/lib/codec/samples.json +13 -0
- package/tools/lib/git.js +16 -0
- package/tools/lib/release-finalize.js +53 -9
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -1652,7 +1652,7 @@ function commentOnce(repoAbs, num, fields, text) {
|
|
|
1652
1652
|
* in (previous final, sha], minus `exclude` (the release tracking issues). Idempotent by event marker.
|
|
1653
1653
|
* Shared by `release finalize` and, on route deploy-tag-fast (#446), `release cut`.
|
|
1654
1654
|
*/
|
|
1655
|
-
function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
|
|
1655
|
+
function announceCarried(repoAbs, { tagNames, exclude, version, sha, early = null }) {
|
|
1656
1656
|
const prev = releaseFinalize.previousFinal(tagNames, version);
|
|
1657
1657
|
if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
|
|
1658
1658
|
const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
|
|
@@ -1663,7 +1663,7 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
|
|
|
1663
1663
|
const view = git.ghIssueView(repoAbs, n, ['comments']);
|
|
1664
1664
|
if (!view) { skipped.push(n); continue; }
|
|
1665
1665
|
if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
|
|
1666
|
-
const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
|
|
1666
|
+
const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha, early));
|
|
1667
1667
|
if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
|
|
1668
1668
|
}
|
|
1669
1669
|
return { range: `${prev}..${version}`, issues: nums, posted, skipped };
|
|
@@ -1967,7 +1967,7 @@ workflow refuses a private repo itself.
|
|
|
1967
1967
|
(publish true, or nothing declared); exit 1 when the npm keys are declared but cannot publish.
|
|
1968
1968
|
`;
|
|
1969
1969
|
|
|
1970
|
-
const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name>]] [--dry] [--json]
|
|
1970
|
+
const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name> [--early]]] [--dry] [--json]
|
|
1971
1971
|
|
|
1972
1972
|
Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
|
|
1973
1973
|
under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
|
|
@@ -1999,7 +1999,8 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
|
|
|
1999
1999
|
|
|
2000
2000
|
Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
|
|
2001
2001
|
release-policy candidate tracking-issue release-hold regressions test-period trunk-green
|
|
2002
|
-
ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant
|
|
2002
|
+
ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant
|
|
2003
|
+
early-final human
|
|
2003
2004
|
|
|
2004
2005
|
regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
|
|
2005
2006
|
began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
|
|
@@ -2037,16 +2038,26 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
2037
2038
|
every row; release-hold and regressions as always. Newer candidates stay open
|
|
2038
2039
|
for the next version — only versions below the final are closed as superseded
|
|
2039
2040
|
--answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
|
|
2040
|
-
No field, flag or project.yml value lowers it, and it never shortens a
|
|
2041
|
-
Where the final is a human act the period is informational anyway,
|
|
2042
|
-
release.test-period: 0d declares none at all (#549)
|
|
2041
|
+
No field, flag or project.yml value lowers it, and on its own it never shortens a
|
|
2042
|
+
test period. Where the final is a human act the period is informational anyway,
|
|
2043
|
+
and release.test-period: 0d declares none at all (#549)
|
|
2044
|
+
--early with COLAB_HUMAN=1, --tag and --answered-by, on a route whose final is automatic
|
|
2045
|
+
(#627): finalize the newest candidate before its test period elapses. The floor
|
|
2046
|
+
binds the machine, not a person who answers for the release: test-period is
|
|
2047
|
+
reported, not required; trunk-green stays required over the elapsed part of the
|
|
2048
|
+
window, and every other check applies. The tag message, the tracking issue and
|
|
2049
|
+
every "Released in" comment record who answered and how much of the period had
|
|
2050
|
+
elapsed. Refused without the bar, on an older candidate, and where the final is
|
|
2051
|
+
already a human act (deploy-tag, or automatic only by release.final-grant).
|
|
2052
|
+
--auto never takes it
|
|
2043
2053
|
--dry measure and report; open, post, tag and close nothing
|
|
2044
2054
|
--json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
|
|
2045
2055
|
periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
|
|
2046
2056
|
skipped (--auto: [{tag, state, detail?}] — the other open candidates),
|
|
2047
2057
|
channel (null, or {channel, ok, action, detail} — the stable move, #445),
|
|
2048
2058
|
announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
|
|
2049
|
-
grant (null, or {issue, ruledBy} — the operator grant that made this final automatic)
|
|
2059
|
+
grant (null, or {issue, ruledBy} — the operator grant that made this final automatic),
|
|
2060
|
+
early (null, or {answeredBy, elapsedHours, periodHours, at} — an early human final, #627) }
|
|
2050
2061
|
|
|
2051
2062
|
Needs origin and gh (the tracking issue, runs and edges live on GitHub). Never cuts a candidate, never
|
|
2052
2063
|
a major, never removes a label or an edge. Exit 0 when finalized (or would be) or candidate-ready; 1
|
|
@@ -2079,17 +2090,21 @@ function releaseHeavyFact(repoAbs, doc, cand) {
|
|
|
2079
2090
|
function cmdReleaseFinalize(argv) {
|
|
2080
2091
|
const opts = parseArgs(argv, {
|
|
2081
2092
|
values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
|
|
2082
|
-
flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
|
|
2093
|
+
flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '--early': 'early', '-h': 'help', '--help': 'help' },
|
|
2083
2094
|
});
|
|
2084
2095
|
if (opts.help) return print(HELP_RELEASE_FINALIZE);
|
|
2085
2096
|
if (opts._.length) throw new UserError(`release finalize takes no positional arguments (got: ${opts._.join(' ')})`);
|
|
2086
2097
|
// #423: --auto is the release workflow's mode. The human bar names one reviewed candidate; --auto
|
|
2087
2098
|
// picks among them — the two never combine, so an unattended run can never carry a human's assertion.
|
|
2088
|
-
if (opts.auto && (opts.tag || opts.answeredBy)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by, or drop --auto');
|
|
2099
|
+
if (opts.auto && (opts.tag || opts.answeredBy || opts.early)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by/--early, or drop --auto');
|
|
2089
2100
|
const humanBar = !opts.auto && process.env.COLAB_HUMAN === '1' && !!opts.answeredBy;
|
|
2090
2101
|
if (humanBar && !opts.tag) {
|
|
2091
2102
|
throw new UserError('the human bar needs --tag <vX.Y.Z-rc.N>: it names the exact candidate the human reviewed, so a newer one cut meanwhile is never finalized in its place');
|
|
2092
2103
|
}
|
|
2104
|
+
// #627: an early final is a human's act alone — refused before anything is read without the whole bar.
|
|
2105
|
+
if (opts.early && !humanBar) {
|
|
2106
|
+
throw new UserError('--early finalizes before the test period elapses only as a human act: run it with COLAB_HUMAN=1, --tag <vX.Y.Z-rc.N> and --answered-by <your name>');
|
|
2107
|
+
}
|
|
2093
2108
|
const repoAbs = resolveRepo(opts);
|
|
2094
2109
|
if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — the tracking issue, runs and regression edges live on GitHub`);
|
|
2095
2110
|
const doc = projectDoc(repoAbs);
|
|
@@ -2222,7 +2237,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
2222
2237
|
ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
|
|
2223
2238
|
heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
|
|
2224
2239
|
manifests, ancestry, tags: tagNames, finalGrant, migrations,
|
|
2225
|
-
human: { bar: humanBar, answeredBy: opts.answeredBy || null },
|
|
2240
|
+
human: { bar: humanBar, answeredBy: opts.answeredBy || null, early: !!opts.early },
|
|
2241
|
+
now, // #627: how much of the period an early final cut short
|
|
2226
2242
|
});
|
|
2227
2243
|
return { candidate: cand, verdict, period, tracking, trunk };
|
|
2228
2244
|
};
|
|
@@ -2281,10 +2297,10 @@ function cmdReleaseFinalize(argv) {
|
|
|
2281
2297
|
// #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
|
|
2282
2298
|
// carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
|
|
2283
2299
|
let announced = null;
|
|
2284
|
-
const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
|
|
2300
|
+
const announceRelease = (version, sha, early = null) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha, early });
|
|
2285
2301
|
if (!opts.dry) {
|
|
2286
2302
|
if (verdict.state === 'finalized') {
|
|
2287
|
-
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})` : ''}`;
|
|
2303
|
+
const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1${verdict.early ? ', --early' : ''})` : `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})` : ''}`;
|
|
2288
2304
|
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
|
|
2289
2305
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
|
|
2290
2306
|
if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
@@ -2318,13 +2334,13 @@ function cmdReleaseFinalize(argv) {
|
|
|
2318
2334
|
`**${cand.tag} is ready.** The final tag is a human act on this repo — the one command, run by a human:\n\n\`\`\`sh\n${verdict.handoff}\n\`\`\``);
|
|
2319
2335
|
}
|
|
2320
2336
|
if (tagged) {
|
|
2321
|
-
comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).`);
|
|
2337
|
+
comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).${verdict.early ? `\n\nEarly final: ${releaseFinalize.earlyLine(verdict.early)}.` : ''}`);
|
|
2322
2338
|
close(tracking.number);
|
|
2323
2339
|
}
|
|
2324
2340
|
}
|
|
2325
2341
|
// #426: every issue the final carries hears which version has it — on the run that tags, and on
|
|
2326
2342
|
// the already-final resume (a run that died between the tag push and these comments finishes them).
|
|
2327
|
-
if (tagged) announced = announceRelease(cand.version, cand.sha);
|
|
2343
|
+
if (tagged) announced = announceRelease(cand.version, cand.sha, verdict.early || null);
|
|
2328
2344
|
// Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
|
|
2329
2345
|
// without --auto closed every other open version at once, because only the newest candidate could
|
|
2330
2346
|
// ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
|
|
@@ -2358,7 +2374,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2358
2374
|
lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
|
|
2359
2375
|
periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
|
|
2360
2376
|
state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
|
|
2361
|
-
skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, channel,
|
|
2377
|
+
skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, early: verdict.early || null, channel,
|
|
2362
2378
|
}, null, 2));
|
|
2363
2379
|
} else {
|
|
2364
2380
|
print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
|
|
@@ -2370,6 +2386,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2370
2386
|
}
|
|
2371
2387
|
print('');
|
|
2372
2388
|
print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
|
|
2389
|
+
if (verdict.early) print(`early final: ${releaseFinalize.earlyLine(verdict.early)}`);
|
|
2373
2390
|
if (why) print(`why no final: ${why.line}`);
|
|
2374
2391
|
if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
|
|
2375
2392
|
if (channel && channel.ok) print(`✓ ${channel.detail}`);
|
|
@@ -11747,6 +11764,12 @@ function classifyCiRunRaw(repoAbs, run, at) {
|
|
|
11747
11764
|
const detail = n === 1 ? `1 run at ${at}: success` : `${n} runs at ${at}: all success`;
|
|
11748
11765
|
return { ok: true, class: null, detail };
|
|
11749
11766
|
}
|
|
11767
|
+
if (run.cancelledOnly) {
|
|
11768
|
+
// #628: one workflow's only run at this sha was cancelled — it verified nothing, and the other
|
|
11769
|
+
// workflows' success does not stand in for it. Name it so a human knows what to re-run.
|
|
11770
|
+
const c = run.cancelledOnly;
|
|
11771
|
+
return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: workflow "${c.workflowName}" never finished here — its only run${c.databaseId ? ` (run ${c.databaseId})` : ''} was cancelled, so it verified nothing; re-run it (#628)` };
|
|
11772
|
+
}
|
|
11750
11773
|
return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=completed conclusion=${run.conclusion || 'none'}` };
|
|
11751
11774
|
}
|
|
11752
11775
|
if (run.status === 'none') {
|
|
@@ -12,6 +12,9 @@ export function decodeTrackingMarker(body: string | null | undefined): string |
|
|
|
12
12
|
export function encodeReleaseEvent(fields: Record<string, string | number>): string;
|
|
13
13
|
export function decodeReleaseEvent(marker: string | null | undefined): Record<string, string> | null;
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
/** #627: an early human final — who answered, and how much of the test period had elapsed. */
|
|
16
|
+
export interface EarlyFinal { answeredBy: string; elapsedHours: number; periodHours: number }
|
|
17
|
+
|
|
18
|
+
export function encodeReleasedComment(c?: { version: string; sha: string; early?: EarlyFinal | null }): string;
|
|
19
|
+
/** `sha` is the 7-character form the comment carries; `early` only when the comment names an early final. */
|
|
20
|
+
export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string; early?: EarlyFinal } | null;
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
* event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
|
|
12
12
|
* tracking issue, keys in the order written. Its exact presence is what makes
|
|
13
13
|
* a re-run post nothing twice, so key order is part of the wire format.
|
|
14
|
-
* released comment — the event marker `released=vX.Y.Z` plus one visible line
|
|
14
|
+
* released comment — the event marker `released=vX.Y.Z` plus one visible line (two after an early
|
|
15
|
+
* human final, #627), posted once on
|
|
15
16
|
* each issue a release carried.
|
|
16
17
|
*
|
|
17
18
|
* Deciding which candidate, which period, and whether to finalize stays in
|
|
@@ -21,7 +22,7 @@
|
|
|
21
22
|
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
22
23
|
const TRACKING_MARKER_RE = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
|
|
23
24
|
const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
|
|
24
|
-
const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)
|
|
25
|
+
const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.(?:\nEarly final: answered by ([^\n]+) after ([0-9]+)h of the ([0-9]+)h test period\.)?$/;
|
|
25
26
|
|
|
26
27
|
/** `vX.Y.Z` → the tracking marker. */
|
|
27
28
|
function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
|
|
@@ -52,16 +53,24 @@ function decodeReleaseEvent(marker) {
|
|
|
52
53
|
return out;
|
|
53
54
|
}
|
|
54
55
|
|
|
55
|
-
/**
|
|
56
|
-
|
|
57
|
-
|
|
56
|
+
/**
|
|
57
|
+
* `{version, sha, early?}` → the "released in" comment; `sha` is shortened to 7 characters. `early`
|
|
58
|
+
* ({answeredBy, elapsedHours, periodHours}, #627) adds one line naming an early human final; without
|
|
59
|
+
* it the comment is byte-identical to the two-line form every earlier final wrote.
|
|
60
|
+
*/
|
|
61
|
+
function encodeReleasedComment({ version, sha, early = null } = {}) {
|
|
62
|
+
const base = `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
|
|
63
|
+
if (!early || !Number.isInteger(early.elapsedHours) || !Number.isInteger(early.periodHours)) return base;
|
|
64
|
+
return `${base}\nEarly final: answered by ${String(early.answeredBy).replace(/\s+/g, ' ').trim()} after ${early.elapsedHours}h of the ${early.periodHours}h test period.`;
|
|
58
65
|
}
|
|
59
66
|
|
|
60
|
-
/** A "released in" comment → `{version, sha}` (sha as written, 7 characters), or null. */
|
|
67
|
+
/** A "released in" comment → `{version, sha}` (sha as written, 7 characters) plus `early` when it names one (#627), or null. */
|
|
61
68
|
function decodeReleasedComment(body) {
|
|
62
69
|
const m = RELEASED_COMMENT_RE.exec(String(body == null ? '' : body).replace(/\r\n/g, '\n').trim());
|
|
63
70
|
if (!m || m[1] !== m[2]) return null;
|
|
64
|
-
|
|
71
|
+
const out = { version: m[1], sha: m[3] };
|
|
72
|
+
if (m[4] !== undefined) out.early = { answeredBy: m[4], elapsedHours: Number(m[5]), periodHours: Number(m[6]) };
|
|
73
|
+
return out;
|
|
65
74
|
}
|
|
66
75
|
|
|
67
76
|
module.exports = {
|
|
@@ -745,6 +745,19 @@
|
|
|
745
745
|
"sha": "3e2f810"
|
|
746
746
|
},
|
|
747
747
|
"note": "synthetic: no final has announced on an issue yet"
|
|
748
|
+
},
|
|
749
|
+
{
|
|
750
|
+
"wire": "<!-- colab:release-event released=v2.4.0 -->\nReleased in **v2.4.0** (`9c1d2e3`).\nEarly final: answered by Ada Lovelace after 30h of the 72h test period.",
|
|
751
|
+
"decoded": {
|
|
752
|
+
"version": "v2.4.0",
|
|
753
|
+
"sha": "9c1d2e3",
|
|
754
|
+
"early": {
|
|
755
|
+
"answeredBy": "Ada Lovelace",
|
|
756
|
+
"elapsedHours": 30,
|
|
757
|
+
"periodHours": 72
|
|
758
|
+
}
|
|
759
|
+
},
|
|
760
|
+
"note": "synthetic: an early human final (#627) — no early final has announced yet"
|
|
748
761
|
}
|
|
749
762
|
]
|
|
750
763
|
},
|
package/tools/lib/git.js
CHANGED
|
@@ -1304,6 +1304,22 @@ function summarizeRepoOwnedRuns(forSha, sha) {
|
|
|
1304
1304
|
);
|
|
1305
1305
|
if (notGreen) return { status: 'completed', conclusion: notGreen.conclusion, sha, createdAt: notGreen.createdAt || null, databaseId: notGreen.databaseId || null, runCount };
|
|
1306
1306
|
|
|
1307
|
+
// #628: a NAMED workflow whose head is `cancelled` has no run at this sha that ran to the end —
|
|
1308
|
+
// newestRunPerWorkflow never lets a cancelled row stand for a workflow that has a non-neutral
|
|
1309
|
+
// run (#92), so a cancelled head means cancelled is all it has. That workflow verified nothing,
|
|
1310
|
+
// and a sibling workflow's success must not carry the verdict for it. Measured: the only test
|
|
1311
|
+
// workflow at a trunk head hung and was cancelled, and the head read GREEN on a lint workflow's
|
|
1312
|
+
// success. Unnamed rows (older reads, hand-built fixtures) stay neutral exactly as before — they
|
|
1313
|
+
// cannot be told apart from a superseded straggler of a passing run, which is #92's case.
|
|
1314
|
+
const cancelledOnly = forSha.find((x) => x && x.workflowName && x.status === 'completed' && x.conclusion === 'cancelled');
|
|
1315
|
+
if (cancelledOnly) {
|
|
1316
|
+
return {
|
|
1317
|
+
status: 'completed', conclusion: 'cancelled', sha, createdAt: cancelledOnly.createdAt || null,
|
|
1318
|
+
databaseId: cancelledOnly.databaseId || null, runCount,
|
|
1319
|
+
cancelledOnly: { workflowName: cancelledOnly.workflowName, databaseId: cancelledOnly.databaseId || null },
|
|
1320
|
+
};
|
|
1321
|
+
}
|
|
1322
|
+
|
|
1307
1323
|
// A green verdict is owed only when EVERY sibling at this sha has finished (#307). A row that is
|
|
1308
1324
|
// still queued/in_progress has not passed — it has not run — so picking the first completed
|
|
1309
1325
|
// success here would stamp `runCount` (the FULL sibling count) onto a verdict that inspected one
|
|
@@ -78,7 +78,7 @@ const STATES = Object.freeze([
|
|
|
78
78
|
const CONDITIONS = Object.freeze([
|
|
79
79
|
'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
|
|
80
80
|
'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
|
|
81
|
-
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
|
|
81
|
+
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'early-final', 'human',
|
|
82
82
|
]);
|
|
83
83
|
|
|
84
84
|
// A completed run with one of these conclusions does not make trunk red.
|
|
@@ -660,14 +660,43 @@ function decide(facts) {
|
|
|
660
660
|
}
|
|
661
661
|
const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
|
|
662
662
|
add('regressions', reg.ok, reg.detail);
|
|
663
|
+
const per = f.period || { elapsed: false, detail: 'not measured' };
|
|
664
|
+
// #627: an early human final. On a route whose final is automatic (and not by an operator's grant —
|
|
665
|
+
// a granted deploy-tag final is already a human act whenever a human runs it), the test-period floor
|
|
666
|
+
// binds the MACHINE: a human who answers for the release (the bar: COLAB_HUMAN=1 + --answered-by,
|
|
667
|
+
// and --early, all three) may finalize the newest candidate before its period elapses. test-period
|
|
668
|
+
// is then reported, not required; trunk-green stays required over the part of the window that has
|
|
669
|
+
// elapsed (the CLI reads it up to now); every other check applies unchanged. --auto never carries
|
|
670
|
+
// the bar, so nothing an agent sets alone shortens a period.
|
|
671
|
+
let early = null;
|
|
672
|
+
if (h.early) {
|
|
673
|
+
const why = !h.bar ? 'needs the human bar (COLAB_HUMAN=1 + --answered-by)'
|
|
674
|
+
: finalMode !== 'auto' ? 'applies only where the final is automatic — here the final is already a human act, and the test period is not required of it'
|
|
675
|
+
: granted ? `applies only where the final is automatic by the row — here it is automatic only by the operator's grant (release.final-grant #${granted.issue}), so a human final already skips the period`
|
|
676
|
+
: s.older ? 'applies only to the newest open candidate — an older one is finalized only once its own period elapsed clean (#548)'
|
|
677
|
+
: null;
|
|
678
|
+
if (why) add('early-final', false, `--early ${why}`);
|
|
679
|
+
else {
|
|
680
|
+
const startMs = Date.parse(per.start);
|
|
681
|
+
const nowMs = Date.parse(f.now);
|
|
682
|
+
const elapsedHours = Number.isNaN(startMs) || Number.isNaN(nowMs) ? null : Math.max(0, Math.floor((nowMs - startMs) / 3600000));
|
|
683
|
+
const periodHours = Number(per.days) * 24;
|
|
684
|
+
early = { answeredBy: h.answeredBy, elapsedHours, periodHours, at: f.now || null };
|
|
685
|
+
add('early-final', true, per.elapsed
|
|
686
|
+
? `--early by ${h.answeredBy}, but the ${per.days}d test period has already elapsed — an ordinary human final`
|
|
687
|
+
: `early human final, answered by ${h.answeredBy}: ${elapsedHours === null ? 'an unknown part' : `${elapsedHours}h`} of the ${periodHours}h test period elapsed — the floor binds the machine, not a person who answers for the release (CONVENTIONS.md §6)`);
|
|
688
|
+
auto = false;
|
|
689
|
+
}
|
|
690
|
+
}
|
|
663
691
|
// #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
|
|
664
692
|
// --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
|
|
665
693
|
// no longer explains why THIS one, and its own clean period is what does.
|
|
666
694
|
const ownClock = auto || !!s.older;
|
|
667
|
-
|
|
668
|
-
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);
|
|
695
|
+
add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : early && !per.elapsed ? `${per.detail} — reported, not required: an early human final (#627)` : per.detail, ownClock);
|
|
669
696
|
const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
|
|
670
|
-
|
|
697
|
+
// #627: an early final keeps trunk-green REQUIRED — over the elapsed part of the window.
|
|
698
|
+
const trunkRequired = ownClock || !!early;
|
|
699
|
+
add('trunk-green', tr.ok, early ? `${tr.detail} (the elapsed part of the window, up to the early final)` : tr.detail, trunkRequired);
|
|
671
700
|
// #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
|
|
672
701
|
// sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
|
|
673
702
|
// those runs counted as passed; it is absent when no such run exists.
|
|
@@ -694,7 +723,7 @@ function decide(facts) {
|
|
|
694
723
|
}
|
|
695
724
|
|
|
696
725
|
if (held.length) return out('held');
|
|
697
|
-
if ((reg.permanent) || (
|
|
726
|
+
if ((reg.permanent) || (trunkRequired && tr.permanent)) return out('needs-new-candidate');
|
|
698
727
|
const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
|
|
699
728
|
&& !(c.condition === 'heavy-lane' && hv && hv.pending));
|
|
700
729
|
if (blocking.length) return out('refused');
|
|
@@ -702,10 +731,14 @@ function decide(facts) {
|
|
|
702
731
|
if (!tr.ok && !tr.pending) return out('refused');
|
|
703
732
|
if (!per.elapsed || tr.pending) return out('testing');
|
|
704
733
|
}
|
|
734
|
+
if (early) {
|
|
735
|
+
if (!tr.ok && !tr.pending) return out('refused');
|
|
736
|
+
if (tr.pending) return out('testing');
|
|
737
|
+
}
|
|
705
738
|
if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
|
|
706
739
|
if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
707
740
|
if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
|
|
708
|
-
return out('finalized', { finalTag: cand.version });
|
|
741
|
+
return out('finalized', { finalTag: cand.version, ...(early && !per.elapsed ? { early } : {}) });
|
|
709
742
|
}
|
|
710
743
|
|
|
711
744
|
// ---- announcing the final (#426) ----------------------------------------------------------------
|
|
@@ -742,8 +775,18 @@ function previousFinal(tagNames, version) {
|
|
|
742
775
|
function releasedEvent(version) { return { released: version }; }
|
|
743
776
|
|
|
744
777
|
/** The comment body posted on each carried issue (marker included) — codec `encodeReleasedComment`. */
|
|
745
|
-
function releasedComment(version, sha) {
|
|
746
|
-
return releaseCodec.encodeReleasedComment({ version, sha });
|
|
778
|
+
function releasedComment(version, sha, early = null) {
|
|
779
|
+
return releaseCodec.encodeReleasedComment({ version, sha, early });
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
/**
|
|
783
|
+
* #627: the one sentence an early human final is recorded with — on the tag, the tracking issue and
|
|
784
|
+
* every "Released in" comment: who answered, how much of the period had elapsed.
|
|
785
|
+
*/
|
|
786
|
+
function earlyLine(early) {
|
|
787
|
+
const e = early || {};
|
|
788
|
+
const part = e.elapsedHours === null || e.elapsedHours === undefined ? 'an unknown part' : `${e.elapsedHours}h`;
|
|
789
|
+
return `answered by ${e.answeredBy} after ${part} of the ${e.periodHours}h test period${e.at ? ` (${e.at})` : ''} — a human final before the period elapsed (CONVENTIONS.md §6)`;
|
|
747
790
|
}
|
|
748
791
|
|
|
749
792
|
/** The final tag's annotated message: which candidate, which period, every condition, who. */
|
|
@@ -754,6 +797,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
|
|
|
754
797
|
`Candidate: ${candidate.tag}`,
|
|
755
798
|
`Commit: ${candidate.sha}`,
|
|
756
799
|
period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
|
|
800
|
+
verdict.early ? `Early final: ${earlyLine(verdict.early)}` : null,
|
|
757
801
|
`Finalized by: ${actor}`,
|
|
758
802
|
verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
|
|
759
803
|
'',
|
|
@@ -767,6 +811,6 @@ module.exports = {
|
|
|
767
811
|
parseVersion, compareVersions, parseCandidate,
|
|
768
812
|
parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
|
|
769
813
|
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
770
|
-
handoffCommand, decide, tagMessage, migrationGrantVerdict,
|
|
814
|
+
handoffCommand, decide, tagMessage, earlyLine, migrationGrantVerdict,
|
|
771
815
|
carriedIssues, previousFinal, releasedEvent, releasedComment,
|
|
772
816
|
};
|