@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1
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/README.md +243 -213
- package/README.vi.md +246 -186
- package/audit/audit.mjs +193 -10
- package/package.json +6 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1691 -254
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +203 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +4 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +151 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +716 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +762 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +303 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/release-cut.js
CHANGED
|
@@ -46,12 +46,27 @@
|
|
|
46
46
|
* section carrying its measured cost (parseMigrationSection). Every signal is written into the tag
|
|
47
47
|
* message, so the reason for the bump is recorded mechanically.
|
|
48
48
|
*
|
|
49
|
-
* Never a final tag
|
|
50
|
-
*
|
|
49
|
+
* Never a final tag — with ONE exception, `deploy-tag-fast` (#446): there the operator granted a
|
|
50
|
+
* final on every green trunk head, so `--auto` tags `vX.Y.Z` directly (no candidate, no test period)
|
|
51
|
+
* and the release workflow deploys it in the same run. That branch adds five checks, all in the
|
|
52
|
+
* same closed vocabulary:
|
|
53
|
+
*
|
|
54
|
+
* spacing --auto only — finals at least release.final-spacing apart; inside the window
|
|
55
|
+
* the run is a NO-OP, and the first run after it tags main's head
|
|
56
|
+
* already-final replaces already-candidate — a head already carrying a final is a NO-OP
|
|
57
|
+
* final-grant the operator's recorded decision still resolves (release-policy.js
|
|
58
|
+
* finalGrantVerdict — the #441 reader, unchanged)
|
|
59
|
+
* release-hold no open issue carries the human veto label
|
|
60
|
+
* migration-grant no migration since the last final unless the version's tracking issue is
|
|
61
|
+
* granted one — otherwise a refusal whose `handoff` names the human command
|
|
62
|
+
*
|
|
63
|
+
* Elsewhere finalizing a candidate is the release skill's (#339), and a final is a human act on
|
|
64
|
+
* every row where a tag reaches production.
|
|
51
65
|
*/
|
|
52
66
|
|
|
53
67
|
const migrationPaths = require('./migration-paths');
|
|
54
68
|
const releaseTag = require('./release-tag');
|
|
69
|
+
const { stripCode } = require('./instruction-file');
|
|
55
70
|
|
|
56
71
|
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
57
72
|
const BUMPS = Object.freeze(['patch', 'minor']);
|
|
@@ -64,11 +79,37 @@ const BUMPS = Object.freeze(['patch', 'minor']);
|
|
|
64
79
|
const RELEASE_BRANCH = 'main';
|
|
65
80
|
|
|
66
81
|
const CONDITIONS = Object.freeze([
|
|
67
|
-
'release-policy', 'cadence', 'promotion', 'prerelease-trigger', 'version', 'already-candidate',
|
|
82
|
+
'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
68
83
|
...releaseTag.PRE_TAG_CONDITIONS,
|
|
69
84
|
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
85
|
+
'final-grant', 'release-hold', 'migration-grant',
|
|
86
|
+
]);
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* #467: the refusals that do NOT clear by themselves. A run refused on one of these refuses again on
|
|
90
|
+
* the next run and the one after — nothing but a human act (a first final tag, a fixed marker, a
|
|
91
|
+
* fixed manifest, a recorded grant) moves it — so the release workflow reports it as a STALL, an
|
|
92
|
+
* error annotation, never as the routine warning a CI-still-running refusal gets. The rest are
|
|
93
|
+
* transient: `ci-green` / `full-suite` (a run in flight, a red run the next merge fixes), an UNREAD
|
|
94
|
+
* anything (a read that failed — the next run reads again), and `release-hold` (a deliberate human
|
|
95
|
+
* veto is not a stall; it is the system working). Classified in decide() as `standing`.
|
|
96
|
+
*/
|
|
97
|
+
const STANDING_CONDITIONS = Object.freeze([
|
|
98
|
+
'release-policy', 'prerelease-trigger', 'version', 'schema-additive', 'switch-dependencies',
|
|
99
|
+
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant',
|
|
70
100
|
]);
|
|
71
101
|
|
|
102
|
+
/** #446: the conditions only route deploy-tag-fast reports. */
|
|
103
|
+
const FAST_CONDITIONS = Object.freeze(['spacing', 'already-final', 'final-grant', 'release-hold', 'migration-grant']);
|
|
104
|
+
|
|
105
|
+
/** #446: the label a human puts on an issue to veto a release — the same one release-finalize reads. */
|
|
106
|
+
const HOLD_LABEL = 'release-hold';
|
|
107
|
+
|
|
108
|
+
/** #446: is this policy the fast route, where `cut --auto` tags the final itself? */
|
|
109
|
+
function isFastRoute(policy) {
|
|
110
|
+
return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
|
|
111
|
+
}
|
|
112
|
+
|
|
72
113
|
/** The file a major's migration section is read from, at the candidate commit (#422). */
|
|
73
114
|
const MIGRATION_FILE = 'MIGRATION.md';
|
|
74
115
|
|
|
@@ -344,7 +385,7 @@ function parseMigrationSection(text, version) {
|
|
|
344
385
|
function decideAutoVersion({ lastFinal, signals, migration, tags }) {
|
|
345
386
|
const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
|
|
346
387
|
const s = signals || { total: 0, breaking: [], minor: [], patch: [], unread: [] };
|
|
347
|
-
if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}
|
|
388
|
+
if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`, { unread: true });
|
|
348
389
|
if (!lastFinal) return refuse('no final release tag (vX.Y.Z) on main yet — the first version is a human decision, not a computed bump');
|
|
349
390
|
const last = parseVersion(lastFinal);
|
|
350
391
|
if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compute a bump from it`);
|
|
@@ -390,6 +431,45 @@ function cadenceVerdict({ candidates, perDay, now }) {
|
|
|
390
431
|
return { ok: false, detail: `${recent.length} candidate(s) in the last 24h (${recent.map((c) => c.name).join(', ')}) — release.candidates-per-day caps at ${perDay} a day; the first run from ${nextAt} cuts main's head, never an older commit`, nextAt };
|
|
391
432
|
}
|
|
392
433
|
|
|
434
|
+
// ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
|
|
435
|
+
|
|
436
|
+
/**
|
|
437
|
+
* Finals at least `spacingHours` apart. `finals` is [{ name, date }] for every final tag (tagger
|
|
438
|
+
* date) — a human's final counts as much as an automatic one. Returns { ok, detail, nextAt }; not ok
|
|
439
|
+
* is a NO-OP for the caller, never a refusal, so the first run after the window tags main's head.
|
|
440
|
+
*/
|
|
441
|
+
function spacingVerdict({ finals, spacingHours, now }) {
|
|
442
|
+
if (!spacingHours) return { ok: true, detail: 'no final spacing on this route', nextAt: null };
|
|
443
|
+
const nowMs = Date.parse(now);
|
|
444
|
+
const dated = (finals || []).map((f) => ({ ...f, ms: Date.parse(f.date) }))
|
|
445
|
+
.filter((f) => !Number.isNaN(f.ms) && f.ms <= nowMs).sort((a, b) => a.ms - b.ms);
|
|
446
|
+
if (!dated.length) return { ok: true, detail: 'no earlier final to space from', nextAt: null };
|
|
447
|
+
const last = dated[dated.length - 1];
|
|
448
|
+
const nextMs = last.ms + spacingHours * 3600000;
|
|
449
|
+
if (nowMs >= nextMs) return { ok: true, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()}, spacing ${spacingHours}h`, nextAt: null };
|
|
450
|
+
const nextAt = new Date(nextMs).toISOString();
|
|
451
|
+
return { ok: false, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()} — release.final-spacing keeps finals ${spacingHours}h apart; the first run from ${nextAt} tags main's head`, nextAt };
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* The human veto, repo-wide: `issues` is the open-issue list (null = unread — never "no hold").
|
|
456
|
+
* Any open issue carrying `release-hold` holds the next final; the fast route has no candidate issue
|
|
457
|
+
* to put the label on, so a human may put it on any issue, and only a human removes it.
|
|
458
|
+
*/
|
|
459
|
+
function holdsVerdict(issues) {
|
|
460
|
+
if (issues === null || issues === undefined) return { ok: false, unread: true, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
|
|
461
|
+
const held = issues.filter((i) => i && (!i.state || String(i.state).toUpperCase() === 'OPEN')
|
|
462
|
+
&& (i.labels || []).some((l) => (l && typeof l === 'object' ? l.name : l) === HOLD_LABEL)).map((i) => i.number);
|
|
463
|
+
return held.length
|
|
464
|
+
? { ok: false, detail: `${HOLD_LABEL} on ${held.map((n) => `#${n}`).join(', ')} — a human veto; no final is tagged while it is present, and no command removes it` }
|
|
465
|
+
: { ok: true, detail: `no open issue carries ${HOLD_LABEL}` };
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/** The command a human runs to let a migration ride an automatic final on the fast route. */
|
|
469
|
+
function migrationHandoff(tracking, version) {
|
|
470
|
+
return `COLAB_HUMAN=1 colab migration-grant ${tracking || '<tracking issue>'} --branch ${version}`;
|
|
471
|
+
}
|
|
472
|
+
|
|
393
473
|
// ---- #443: the newest candidate names trunk's head -------------------------------------------
|
|
394
474
|
|
|
395
475
|
/** Events that run DOWNSTREAM of the suite (the release workflow itself) — never part of "head is green". */
|
|
@@ -414,16 +494,22 @@ const DOWNSTREAM_EVENTS = Object.freeze(['workflow_run', 'schedule', 'workflow_d
|
|
|
414
494
|
* whole suite-duration after it went green is one the release run did not tag.
|
|
415
495
|
*
|
|
416
496
|
* Returns { state, flag, detail, greenAt, cycleMs } — state is one of: off · named · nothing-owed ·
|
|
417
|
-
* not-promotion · unread · not-green · pending · untagged.
|
|
497
|
+
* no-final · not-promotion · unread · not-green · pending · untagged. `untagged` and `no-final` flag.
|
|
498
|
+
*
|
|
499
|
+
* `no-final` (#467): candidates are automatic but there is no final tag to compute a bump from, so
|
|
500
|
+
* `release cut --auto` refuses on every run, forever, until a human tags the first version. That is a
|
|
501
|
+
* stall, not "nothing owed" — reading it as nothing-owed is how a repo sat green for days with no tag.
|
|
418
502
|
*/
|
|
419
503
|
function headCandidateVerdict({ candidatesAuto, sha, tagsAtSha, owed, runs, promotion, now }) {
|
|
420
504
|
const at = `main@${String(sha || '').slice(0, 7)}`;
|
|
421
|
-
const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged', detail, greenAt: null, cycleMs: null, ...extra });
|
|
505
|
+
const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged' || state === 'no-final', detail, greenAt: null, cycleMs: null, ...extra });
|
|
422
506
|
if (!candidatesAuto) return out('off', 'candidates are not automatic here — nothing names the head by itself');
|
|
423
507
|
const named = (tagsAtSha || []).filter((t) => /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t));
|
|
424
508
|
if (named.length) return out('named', `${at} is ${named.join(', ')}`);
|
|
425
509
|
if (owed === 0) return out('nothing-owed', `nothing merged on main since the last final — no candidate is owed`);
|
|
426
|
-
if (owed === null || owed === undefined)
|
|
510
|
+
if (owed === null || owed === undefined) {
|
|
511
|
+
return out('no-final', 'no final tag yet — `release cut --auto` refuses every run until a human tags the first version (CONVENTIONS.md §6, Versioning); release stalled');
|
|
512
|
+
}
|
|
427
513
|
if (promotion && !promotion.ok) return out('not-promotion', `${at} is not a promotion of trunk — --auto never cuts it (${promotion.detail})`);
|
|
428
514
|
if (!Array.isArray(runs)) return out('unread', `gh run list failed — cannot tell whether ${at} is green`);
|
|
429
515
|
const suite = runs.filter((r) => r && !DOWNSTREAM_EVENTS.includes(r.event));
|
|
@@ -452,6 +538,28 @@ function prereleaseArgs(tag, notesFile) {
|
|
|
452
538
|
return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--prerelease', '--latest=false'];
|
|
453
539
|
}
|
|
454
540
|
|
|
541
|
+
/** #446: a deploy-tag-fast final's GitHub Release — a full release, marked latest. */
|
|
542
|
+
function finalReleaseArgs(tag, notesFile) {
|
|
543
|
+
return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--latest'];
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/**
|
|
547
|
+
* #446: the tracking issue a fast-route migration hand-off opens. Same marker as release-finalize's
|
|
548
|
+
* (`<!-- colab:release version=… -->`), so every reader finds it; the text says what is owed here —
|
|
549
|
+
* a migration grant, not a candidate's test period.
|
|
550
|
+
*/
|
|
551
|
+
function handoffTrackingBody(version) {
|
|
552
|
+
return [
|
|
553
|
+
`<!-- colab:release version=${version} -->`,
|
|
554
|
+
'',
|
|
555
|
+
`Release tracking record for **${version}** — opened by \`colab release cut --auto\` on route \`deploy-tag-fast\` (CONVENTIONS.md §6). A record, not a unit of work: never claimed, never started.`,
|
|
556
|
+
'',
|
|
557
|
+
'- The final is automatic on every green head, by the operator\'s grant — but a database migration since the last final never rides an automatic deploy ungranted.',
|
|
558
|
+
`- **To let it ride:** a human runs \`COLAB_HUMAN=1 colab migration-grant <this issue> --branch ${version}\`; the next green run tags and deploys ${version}.`,
|
|
559
|
+
`- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
|
|
560
|
+
].join('\n') + '\n';
|
|
561
|
+
}
|
|
562
|
+
|
|
455
563
|
// ---- §6 condition 2: the full suite ------------------------------------------------------------
|
|
456
564
|
|
|
457
565
|
/**
|
|
@@ -577,11 +685,16 @@ const MARKER_RE = /<!--\s*colab:switch\b([\s\S]*?)-->/g;
|
|
|
577
685
|
* Returns { markers: [{ name, needs: [], role: null|'add'|'remove' }], malformed: [text] } — an
|
|
578
686
|
* unknown token, a bad name, `needs` on a child, or two markers for one name disagreeing are all
|
|
579
687
|
* `malformed`: "not cleared", reported, never defaulted.
|
|
688
|
+
*
|
|
689
|
+
* #466: fenced code blocks and inline code spans are blanked first (`stripCode`, the same reader
|
|
690
|
+
* the instruction-file import scan uses), so a body that QUOTES the marker family — prose such as
|
|
691
|
+
* "the `<!-- colab:switch -->` marker" — is documentation, not a malformed marker blocking every
|
|
692
|
+
* release. A real marker sits outside code, so it is still read, and still refused when malformed.
|
|
580
693
|
*/
|
|
581
694
|
function parseSwitchMarkers(body) {
|
|
582
695
|
const markers = [];
|
|
583
696
|
const malformed = [];
|
|
584
|
-
const text = String(body || '');
|
|
697
|
+
const text = stripCode(String(body || '')).join('\n');
|
|
585
698
|
let m;
|
|
586
699
|
MARKER_RE.lastIndex = 0;
|
|
587
700
|
while ((m = MARKER_RE.exec(text)) !== null) {
|
|
@@ -632,7 +745,7 @@ function closedDone(issue) {
|
|
|
632
745
|
* here: this is the release-time consequence, not the edge audit.
|
|
633
746
|
*/
|
|
634
747
|
function switchVerdict(issues) {
|
|
635
|
-
if (issues === null || issues === undefined) return { ok: false, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
|
|
748
|
+
if (issues === null || issues === undefined) return { ok: false, unread: true, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
|
|
636
749
|
const problems = [];
|
|
637
750
|
const needsOf = new Map(); // name -> { needs: [..], from: #N }
|
|
638
751
|
const declared = new Set();
|
|
@@ -706,12 +819,24 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
|
|
|
706
819
|
function decide(facts) {
|
|
707
820
|
const f = facts || {};
|
|
708
821
|
const checks = [];
|
|
709
|
-
|
|
822
|
+
// #467: `unread` marks a failure that is a failed READ, not a measured fact — the next run reads
|
|
823
|
+
// again, so it is never a standing refusal. Kept out of the check rows (their shape is frozen).
|
|
824
|
+
const unreadSet = new Set();
|
|
825
|
+
const add = (condition, ok, detail, unread) => {
|
|
826
|
+
checks.push({ condition, ok: !!ok, detail });
|
|
827
|
+
if (!ok && unread) unreadSet.add(condition);
|
|
828
|
+
};
|
|
829
|
+
const isUnread = (verdict) => !!(verdict && verdict.unread);
|
|
710
830
|
|
|
711
831
|
const p = f.policy;
|
|
712
|
-
|
|
832
|
+
const fast = isFastRoute(p) && !(p.findings && p.findings.length);
|
|
833
|
+
if (!p) add('release-policy', false, 'no release policy was evaluated', true);
|
|
713
834
|
else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
|
|
714
|
-
else if (
|
|
835
|
+
else if (fast && !f.auto) {
|
|
836
|
+
add('release-policy', false, 'route deploy-tag-fast tags its finals only from the release workflow (`colab release cut --auto`), where the deploy runs in the same run — a final cut by hand would reach production with no deploy job behind it');
|
|
837
|
+
} else if (fast) {
|
|
838
|
+
add('release-policy', true, `${p.derived.axis} (${p.derived.row}, route deploy-tag-fast): a final on every green head, granted by decision #${p.effective.finalGrant.issue}, health gate ${p.effective.healthGate.url} (rollback: ${p.effective.healthGate.rollback}), spacing ${p.effective.finalSpacingHours}h`);
|
|
839
|
+
} else if (p.effective.candidates !== 'auto') {
|
|
715
840
|
const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
|
|
716
841
|
add('release-policy', false, narrowed
|
|
717
842
|
? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
|
|
@@ -724,12 +849,17 @@ function decide(facts) {
|
|
|
724
849
|
let noop = false;
|
|
725
850
|
if (f.auto) {
|
|
726
851
|
const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
|
|
727
|
-
add('cadence', cad.ok, cad.detail);
|
|
852
|
+
add('cadence', cad.ok, cad.detail, !f.auto.cadence);
|
|
728
853
|
if (!cad.ok) noop = !!f.auto.cadence;
|
|
854
|
+
if (fast) {
|
|
855
|
+
const sp = f.auto.spacing || { ok: false, detail: 'final spacing not measured' };
|
|
856
|
+
add('spacing', sp.ok, sp.detail);
|
|
857
|
+
if (!sp.ok && f.auto.spacing) noop = true;
|
|
858
|
+
}
|
|
729
859
|
// #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
|
|
730
860
|
const pr = f.auto.promotion;
|
|
731
861
|
if (pr) {
|
|
732
|
-
add('promotion', pr.ok, pr.detail);
|
|
862
|
+
add('promotion', pr.ok, pr.detail, isUnread(pr));
|
|
733
863
|
if (!pr.ok && !pr.unread) noop = true;
|
|
734
864
|
}
|
|
735
865
|
}
|
|
@@ -741,13 +871,22 @@ function decide(facts) {
|
|
|
741
871
|
const v = f.auto
|
|
742
872
|
? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
|
|
743
873
|
: decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
|
|
744
|
-
add('version', v.ok, v.detail);
|
|
874
|
+
add('version', v.ok, v.detail, isUnread(v));
|
|
745
875
|
// "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
|
|
746
876
|
if (f.auto && v.nothing) noop = true;
|
|
747
877
|
|
|
748
878
|
let tag = null;
|
|
749
879
|
let derivable = [];
|
|
750
|
-
if (v.ok) {
|
|
880
|
+
if (v.ok && fast) {
|
|
881
|
+
const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
|
|
882
|
+
if (finalHere.length) {
|
|
883
|
+
add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
|
|
884
|
+
if (f.auto) noop = true;
|
|
885
|
+
} else {
|
|
886
|
+
tag = v.version;
|
|
887
|
+
add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
|
|
888
|
+
}
|
|
889
|
+
} else if (v.ok) {
|
|
751
890
|
const here = candidateNumbers(f.tagsAtSha || [], v.version);
|
|
752
891
|
if (here.length) {
|
|
753
892
|
add('already-candidate', false, `this commit is already ${v.version}-rc.${here[here.length - 1]} — a second candidate for the same commit tests nothing new`);
|
|
@@ -763,7 +902,10 @@ function decide(facts) {
|
|
|
763
902
|
// #424: the three pre-tag checks, on the tag this run would create.
|
|
764
903
|
if (tag) {
|
|
765
904
|
for (const c of releaseTag.preTagChecks({ tag, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: RELEASE_BRANCH, versionSource: versionSourceOf(p) })) {
|
|
766
|
-
|
|
905
|
+
// An unread manifest list or an unmeasured ancestry is a failed read, not a wrong manifest.
|
|
906
|
+
const unreadPre = (c.condition === 'manifest-version' && (f.manifests === null || f.manifests === undefined))
|
|
907
|
+
|| (c.condition === 'on-trunk' && !f.ancestry);
|
|
908
|
+
add(c.condition, c.ok, c.detail, unreadPre);
|
|
767
909
|
if (c.derivable && c.derivable.length) derivable = c.derivable;
|
|
768
910
|
}
|
|
769
911
|
} else if (f.ancestry && f.ancestry.shallow) {
|
|
@@ -772,17 +914,39 @@ function decide(facts) {
|
|
|
772
914
|
}
|
|
773
915
|
|
|
774
916
|
for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
775
|
-
if (!verdict) add(condition, false, 'not measured');
|
|
776
|
-
else add(condition, verdict.ok, verdict.detail);
|
|
917
|
+
if (!verdict) add(condition, false, 'not measured', true);
|
|
918
|
+
else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
|
|
919
|
+
}
|
|
920
|
+
|
|
921
|
+
// #446: what the fast route keeps in place of the test period it does not have.
|
|
922
|
+
let handoff = null;
|
|
923
|
+
let grant = null;
|
|
924
|
+
if (fast) {
|
|
925
|
+
const g = f.finalGrant || { ok: false, detail: `release.final-grant #${p.effective.finalGrant.issue} was not resolved — an unresolved grant is not a grant` };
|
|
926
|
+
add('final-grant', g.ok, g.detail, !f.finalGrant || isUnread(g));
|
|
927
|
+
if (g.ok) grant = { issue: p.effective.finalGrant.issue, ruledBy: g.ruledBy || null };
|
|
928
|
+
const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
|
|
929
|
+
add('release-hold', h.ok, h.detail, !f.holds || isUnread(h));
|
|
930
|
+
const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
|
|
931
|
+
add('migration-grant', mig.ok, mig.detail, !f.migrations || isUnread(mig));
|
|
932
|
+
if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
|
|
777
933
|
}
|
|
778
934
|
|
|
779
935
|
const refusals = checks.filter((c) => !c.ok);
|
|
780
936
|
const ok = refusals.length === 0 && !!tag;
|
|
937
|
+
// #467: the refusals that will not clear by themselves — empty on ok and on a no-op, whose
|
|
938
|
+
// "failures" (cadence, nothing merged, head already a candidate) are the route holding.
|
|
939
|
+
const standing = ok || noop ? [] : refusals
|
|
940
|
+
.filter((c) => STANDING_CONDITIONS.includes(c.condition) && !unreadSet.has(c.condition))
|
|
941
|
+
.map((c) => c.condition);
|
|
781
942
|
return {
|
|
782
|
-
ok, noop: !ok && noop, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
|
|
943
|
+
ok, noop: !ok && noop, standing, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
|
|
783
944
|
bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
|
|
784
945
|
signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
|
|
785
946
|
derivable,
|
|
947
|
+
versionSourceDeclared: !!(p && p.effective && p.effective.versionSourceDeclared),
|
|
948
|
+
final: fast, grant, handoff,
|
|
949
|
+
healthGate: fast ? p.effective.healthGate : null,
|
|
786
950
|
};
|
|
787
951
|
}
|
|
788
952
|
|
|
@@ -793,8 +957,11 @@ function versionSourceOf(policy) {
|
|
|
793
957
|
|
|
794
958
|
/** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
|
|
795
959
|
function tagMessage(verdict, { sha, lastFinal }) {
|
|
960
|
+
// #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
|
|
961
|
+
// reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
|
|
962
|
+
const fast = !!verdict.final;
|
|
796
963
|
const lines = [
|
|
797
|
-
`${verdict.tag} — release candidate (colab release cut)`,
|
|
964
|
+
fast ? `${verdict.tag} — release (colab release cut, deploy-tag-fast)` : `${verdict.tag} — release candidate (colab release cut)`,
|
|
798
965
|
'',
|
|
799
966
|
`Commit: ${sha}`,
|
|
800
967
|
`Since: ${lastFinal}`,
|
|
@@ -802,21 +969,28 @@ function tagMessage(verdict, { sha, lastFinal }) {
|
|
|
802
969
|
'',
|
|
803
970
|
...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
|
|
804
971
|
...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
|
|
805
|
-
...(
|
|
972
|
+
...(fast && 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 route: deploy-tag, revokes it)`] : []),
|
|
973
|
+
...(fast && verdict.healthGate ? [`Health gate: ${verdict.healthGate.url} (rollback: ${verdict.healthGate.rollback}) — the release workflow deploys this tag in the same run and verifies it there`, ''] : []),
|
|
974
|
+
// #484: a defaulted `tag` says so — the stale manifest is named on every cut, so an artifact that
|
|
975
|
+
// reads it unstamped is visible here rather than discovered by a user.
|
|
976
|
+
...(verdict.derivable && verdict.derivable.length ? [verdict.versionSourceDeclared
|
|
977
|
+
? `Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`
|
|
978
|
+
: `Derivable manifests (release.version-source: tag — the default on a route that tags automatically, #484; not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
|
|
806
979
|
'Conditions (CONVENTIONS.md §6):',
|
|
807
980
|
...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
|
|
808
981
|
'',
|
|
809
|
-
'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
|
|
982
|
+
fast ? 'A final with no candidate: route deploy-tag-fast, by the operator\'s grant (CONVENTIONS.md §6).' : 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
|
|
810
983
|
];
|
|
811
984
|
return lines.join('\n') + '\n';
|
|
812
985
|
}
|
|
813
986
|
|
|
814
987
|
module.exports = {
|
|
815
|
-
CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH,
|
|
988
|
+
CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
989
|
+
isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
816
990
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
817
991
|
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
818
992
|
fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
|
|
819
993
|
parseSwitchMarkers, switchVerdict,
|
|
820
994
|
promotionVerdict, decide, tagMessage, versionSourceOf,
|
|
821
|
-
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs,
|
|
995
|
+
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
|
|
822
996
|
};
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* PURE BY CONSTRUCTION, the release-cut.js posture: no git, no network, no `gh`, no clock (`now` is
|
|
10
10
|
* passed in). The CLI in tools/colab is the measuring half.
|
|
11
11
|
*
|
|
12
|
-
* WHERE PER-CANDIDATE STATE LIVES (the contract
|
|
13
|
-
* consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
|
|
12
|
+
* WHERE PER-CANDIDATE STATE LIVES (the contract a downstream dashboard's release view reads — change
|
|
13
|
+
* it and every consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
|
|
14
14
|
*
|
|
15
15
|
* - the candidates are the annotated `vX.Y.Z-rc.N` tags on origin that `colab release cut` made
|
|
16
16
|
* (first line of the tag message ends `(colab release cut)`); nothing else stores them;
|
|
@@ -56,7 +56,11 @@
|
|
|
56
56
|
|
|
57
57
|
const releaseTag = require('./release-tag');
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
// The tracking marker and the event marker are wire format: codec/release.js (#498, epic #496),
|
|
60
|
+
// re-exported below under the names this module always had. VERSION_RE is the codec's, so a
|
|
61
|
+
// marker's version and a tag's version are judged by one pattern.
|
|
62
|
+
const releaseCodec = require('./codec/release');
|
|
63
|
+
const { VERSION_RE } = releaseCodec;
|
|
60
64
|
const CANDIDATE_RE = /^(v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))-rc\.([1-9][0-9]*)$/;
|
|
61
65
|
const CUT_SUBJECT_SUFFIX = '(colab release cut)';
|
|
62
66
|
const HOLD_LABEL = 'release-hold';
|
|
@@ -93,20 +97,11 @@ function parseCandidate(tag) {
|
|
|
93
97
|
|
|
94
98
|
// ---- the tracking issue -------------------------------------------------------------------------
|
|
95
99
|
|
|
96
|
-
const RELEASE_MARKER_RE = /<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
|
|
97
|
-
|
|
98
100
|
/** The version a tracking issue's body declares, or null. Only the marker counts, never the title. */
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
return m && parseVersion(m[1]) ? m[1] : null;
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
function releaseMarker(version) { return `<!-- colab:release version=${version} -->`; }
|
|
105
|
-
|
|
101
|
+
const parseReleaseMarker = releaseCodec.decodeTrackingMarker;
|
|
102
|
+
const releaseMarker = releaseCodec.encodeTrackingMarker;
|
|
106
103
|
/** `<!-- colab:release-event k=v … -->`, keys in the order given. */
|
|
107
|
-
|
|
108
|
-
return `<!-- colab:release-event ${Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(' ')} -->`;
|
|
109
|
-
}
|
|
104
|
+
const eventMarker = releaseCodec.encodeReleaseEvent;
|
|
110
105
|
|
|
111
106
|
/** True when some comment body already carries exactly this event marker — a re-run posts nothing twice. */
|
|
112
107
|
function hasEvent(comments, fields) {
|
|
@@ -202,18 +197,102 @@ function openCandidates(tags, remote = 'origin') {
|
|
|
202
197
|
}
|
|
203
198
|
|
|
204
199
|
/**
|
|
205
|
-
*
|
|
206
|
-
*
|
|
200
|
+
* #468: the one check that explains a verdict's state, as `<condition>: <detail>` — or null when the
|
|
201
|
+
* state needs no explaining (finalized, already-final). What a reader of a run needs is WHY this
|
|
202
|
+
* candidate did not finalize, not the whole checklist again.
|
|
203
|
+
*/
|
|
204
|
+
function stateDetail(verdict) {
|
|
205
|
+
const v = verdict || {};
|
|
206
|
+
const checks = v.checks || [];
|
|
207
|
+
const failing = (name) => checks.find((c) => c.condition === name && !c.ok);
|
|
208
|
+
const fmt = (c) => (c ? `${c.condition}: ${c.detail}` : null);
|
|
209
|
+
switch (v.state) {
|
|
210
|
+
case 'finalized': case 'already-final': return null;
|
|
211
|
+
case 'held': return fmt(failing('release-hold'));
|
|
212
|
+
case 'needs-new-candidate': return fmt(failing('regressions') || failing('trunk-green'));
|
|
213
|
+
case 'testing': return fmt(failing('test-period') || failing('trunk-green'));
|
|
214
|
+
case 'candidate-ready': return fmt(failing('human'));
|
|
215
|
+
default: return fmt(checks.find((c) => c.required !== false && !c.ok) || checks.find((c) => !c.ok));
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* --auto (#423): `evaluations` is [{ candidate, verdict, period? }] NEWEST FIRST, one decide() per
|
|
221
|
+
* candidate judged. Returns { candidate, verdict, skipped: [{ tag, state, detail, endsAt }] }:
|
|
207
222
|
* - any `held` verdict wins outright — a human veto is never walked around;
|
|
208
223
|
* - else the first `finalized` (the newest candidate clean on its own clock);
|
|
209
224
|
* - else the newest candidate's verdict (testing, refused …), with the older ones listed as skipped.
|
|
225
|
+
* #468: each skipped entry says why (stateDetail) and when its own period ends, so a run that
|
|
226
|
+
* finalizes nothing can say which candidate finals first — the fallback to the newest candidate
|
|
227
|
+
* otherwise reads exactly like "only the newest candidate is considered".
|
|
210
228
|
*/
|
|
211
229
|
function pickNewestClean(evaluations) {
|
|
212
230
|
const ev = evaluations || [];
|
|
213
231
|
if (!ev.length) return { candidate: null, verdict: null, skipped: [] };
|
|
214
232
|
const held = ev.find((e) => e.verdict.state === 'held');
|
|
215
233
|
const pick = held || ev.find((e) => e.verdict.state === 'finalized') || ev[0];
|
|
216
|
-
return {
|
|
234
|
+
return {
|
|
235
|
+
candidate: pick.candidate,
|
|
236
|
+
verdict: pick.verdict,
|
|
237
|
+
skipped: ev.filter((e) => e !== pick).map((e) => ({
|
|
238
|
+
tag: e.candidate.tag, state: e.verdict.state, detail: stateDetail(e.verdict), endsAt: e.period ? e.period.endsAt : null,
|
|
239
|
+
})),
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* #468: is any red trunk run (`redAts`, ISO createdAt times from trunkGreenVerdict's `redAt`) inside
|
|
245
|
+
* this candidate's own window [start, endsAt)? The window is half-open exactly as trunkGreenVerdict
|
|
246
|
+
* reads it. True means the candidate would read `needs-new-candidate` — IF the red run's workflow is
|
|
247
|
+
* among the ones that vetted it; that is only known after a full judge, so a true here may be wrong
|
|
248
|
+
* in the safe direction only: a final delayed, never one made.
|
|
249
|
+
*/
|
|
250
|
+
function windowHasRed(period, redAts) {
|
|
251
|
+
if (!period) return null;
|
|
252
|
+
const startMs = Date.parse(period.start);
|
|
253
|
+
const endMs = Date.parse(period.endsAt);
|
|
254
|
+
return (redAts || []).find((t) => { const ms = Date.parse(t); return ms >= startMs && ms < endMs; }) || null;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* #468: why a run produced no final, in one line, plus the candidate that finals first.
|
|
259
|
+
* state, candidate, checks the picked verdict (and its candidate) — the run's reported state
|
|
260
|
+
* period the picked candidate's own period, or null
|
|
261
|
+
* skipped pickNewestClean's skipped list, the cheap-skipped testing ones included
|
|
262
|
+
* now ISO timestamp (the module stays clock-free)
|
|
263
|
+
* Returns null when a final was made (or the version is already final); else { line, next } where
|
|
264
|
+
* `next` = { tag, endsAt, hoursLeft } for the TESTING candidate whose own period ends soonest, or null.
|
|
265
|
+
*/
|
|
266
|
+
function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
|
|
267
|
+
if (state === 'finalized' || state === 'already-final') return null;
|
|
268
|
+
const nowMs = Date.parse(now);
|
|
269
|
+
const testing = [
|
|
270
|
+
...(state === 'testing' && candidate && period ? [{ tag: candidate.tag, endsAt: period.endsAt }] : []),
|
|
271
|
+
...(skipped || []).filter((x) => x.state === 'testing' && x.endsAt),
|
|
272
|
+
].filter((x) => !Number.isNaN(Date.parse(x.endsAt)));
|
|
273
|
+
testing.sort((a, b) => Date.parse(a.endsAt) - Date.parse(b.endsAt) || String(a.tag).localeCompare(String(b.tag)));
|
|
274
|
+
const first = testing[0] || null;
|
|
275
|
+
const next = first
|
|
276
|
+
? { tag: first.tag, endsAt: first.endsAt, hoursLeft: Number.isNaN(nowMs) ? null : Math.max(0, Math.ceil((Date.parse(first.endsAt) - nowMs) / 3600000)) }
|
|
277
|
+
: null;
|
|
278
|
+
const nextText = next ? `${next.tag} is first, its own test period ends ${next.endsAt}${next.hoursLeft !== null ? ` (${next.hoursLeft}h left)` : ''}` : null;
|
|
279
|
+
const why = stateDetail({ state, checks });
|
|
280
|
+
const tag = candidate ? candidate.tag : 'no candidate';
|
|
281
|
+
let line;
|
|
282
|
+
if (state === 'no-candidate') line = `no open candidate to finalize${why ? ` — ${why}` : ''}`;
|
|
283
|
+
else if (state === 'testing') {
|
|
284
|
+
const allTesting = (skipped || []).every((x) => x.state === 'testing');
|
|
285
|
+
line = allTesting && nextText
|
|
286
|
+
? `no candidate's own test period has elapsed clean — ${nextText}`
|
|
287
|
+
: `${tag} is still testing (${why || 'test period'})${nextText ? `; ${nextText}` : ''}`;
|
|
288
|
+
} else line = `${tag}: ${state}${why ? ` — ${why}` : ''}${nextText ? `; ${nextText}` : ''}`;
|
|
289
|
+
const older = (skipped || []).filter((x) => x.state !== 'testing');
|
|
290
|
+
if (older.length && state === 'testing') {
|
|
291
|
+
const counts = {};
|
|
292
|
+
for (const x of older) counts[x.state] = (counts[x.state] || 0) + 1;
|
|
293
|
+
line += `; older candidates: ${Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ')}`;
|
|
294
|
+
}
|
|
295
|
+
return { line, next };
|
|
217
296
|
}
|
|
218
297
|
|
|
219
298
|
// ---- the test period ----------------------------------------------------------------------------
|
|
@@ -263,7 +342,9 @@ function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows
|
|
|
263
342
|
const inWindow = runs.filter((r) => r && Date.parse(r.createdAt) >= startMs && Date.parse(r.createdAt) < endMs && suite.has(r.workflowName || '(unnamed workflow)') && r.event !== 'pull_request');
|
|
264
343
|
const red = inWindow.filter((r) => r.status === 'completed' && !NOT_RED.has(r.conclusion) && r.conclusion !== 'cancelled');
|
|
265
344
|
if (red.length) {
|
|
266
|
-
|
|
345
|
+
// #468: redAt — when each red run started — lets an --auto walk skip older candidates whose
|
|
346
|
+
// window holds the same red run without paying a full judge for each (windowHasRed).
|
|
347
|
+
return { ok: false, permanent: true, pending: false, redAt: red.map((r) => r.createdAt), detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
|
|
267
348
|
}
|
|
268
349
|
const unsettled = [];
|
|
269
350
|
let pending = inWindow.some((r) => r.status !== 'completed');
|
|
@@ -342,7 +423,7 @@ function regressionVerdict(edges, { periodStart }) {
|
|
|
342
423
|
* evaluate. Returns { ok, detail }.
|
|
343
424
|
*/
|
|
344
425
|
function migrationGrantVerdict({ paths, grant, since }) {
|
|
345
|
-
if (paths === null || paths === undefined) return { ok: false, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
|
|
426
|
+
if (paths === null || paths === undefined) return { ok: false, unread: true, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
|
|
346
427
|
if (!paths.length) return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|
|
347
428
|
const list = paths.join(', ');
|
|
348
429
|
if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
|
|
@@ -397,6 +478,13 @@ function decide(facts) {
|
|
|
397
478
|
else if (!/^released-/.test(row)) add('release-policy', false, `${p.derived.axis}: ${p.derived.why} — nothing to finalize here (CONVENTIONS.md §6, The release rung)`);
|
|
398
479
|
else add('release-policy', true, `${p.derived.axis} (${row}): final ${finalMode}, test period ${p.effective.testPeriodDays}d`);
|
|
399
480
|
if (!checks[0].ok) return out('refused');
|
|
481
|
+
// #446: route deploy-tag-fast tags its finals in `release cut --auto`, with no candidate. A leftover
|
|
482
|
+
// candidate from an earlier route is superseded by the next final — never finalized here, where the
|
|
483
|
+
// grant would otherwise finalize an old -rc days after the operator chose the fast route.
|
|
484
|
+
if (p.effective.finalize === 'on-green-head') {
|
|
485
|
+
add('candidate', false, 'route deploy-tag-fast cuts its finals in `colab release cut --auto` on every green head — there is no candidate to finalize; one left over from an earlier route is superseded by the next final');
|
|
486
|
+
return out('no-candidate');
|
|
487
|
+
}
|
|
400
488
|
|
|
401
489
|
const s = f.selection || { kind: 'none', detail: 'no candidate selected' };
|
|
402
490
|
if (s.kind === 'none') { add('candidate', false, s.detail); return out('no-candidate'); }
|
|
@@ -490,9 +578,9 @@ function previousFinal(tagNames, version) {
|
|
|
490
578
|
/** The event fields of a "released in" comment — one per issue per version. */
|
|
491
579
|
function releasedEvent(version) { return { released: version }; }
|
|
492
580
|
|
|
493
|
-
/** The comment body posted on each carried issue (marker included)
|
|
581
|
+
/** The comment body posted on each carried issue (marker included) — codec `encodeReleasedComment`. */
|
|
494
582
|
function releasedComment(version, sha) {
|
|
495
|
-
return
|
|
583
|
+
return releaseCodec.encodeReleasedComment({ version, sha });
|
|
496
584
|
}
|
|
497
585
|
|
|
498
586
|
/** The final tag's annotated message: which candidate, which period, every condition, who. */
|
|
@@ -515,7 +603,7 @@ module.exports = {
|
|
|
515
603
|
STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
|
|
516
604
|
parseVersion, compareVersions, parseCandidate,
|
|
517
605
|
parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
|
|
518
|
-
selectCandidate, openCandidates, pickNewestClean, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
606
|
+
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
519
607
|
handoffCommand, decide, tagMessage, migrationGrantVerdict,
|
|
520
608
|
carriedIssues, previousFinal, releasedEvent, releasedComment,
|
|
521
609
|
};
|