@futurelastic/colab-handbook 1.12.0-rc.19 → 1.12.0-rc.20
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/audit/audit.mjs +44 -2
- package/package.json +1 -1
- package/templates/release-auto.yml +77 -0
- package/tools/colab +151 -27
- package/tools/lib/release-cut.js +137 -9
- package/tools/lib/release-finalize.js +7 -0
- package/tools/lib/release-policy.js +85 -11
package/audit/audit.mjs
CHANGED
|
@@ -1432,7 +1432,11 @@ function auditRepo(target, ctx) {
|
|
|
1432
1432
|
if (grant) {
|
|
1433
1433
|
const v = releasePolicy.finalGrantVerdict(src.issue ? src.issue(grant.issue) : null, { issue: grant.issue, trust: trustHumansLib.parseTrustHumans(cfg) });
|
|
1434
1434
|
info.releaseFinalGrant = { issue: grant.issue, ok: v.ok, ruledBy: v.ruledBy };
|
|
1435
|
-
if (!v.ok)
|
|
1435
|
+
if (!v.ok) {
|
|
1436
|
+
fail(rel.effective.route === releasePolicy.FAST_ROUTE
|
|
1437
|
+
? `route: deploy-tag-fast has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, A final on every green head)`
|
|
1438
|
+
: `release.final: auto on deploy-tag has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, An operator-granted automatic final)`);
|
|
1439
|
+
}
|
|
1436
1440
|
}
|
|
1437
1441
|
}
|
|
1438
1442
|
|
|
@@ -1642,6 +1646,7 @@ function auditRepo(target, ctx) {
|
|
|
1642
1646
|
const deployWorkflows = workflows.filter((f) => /^deploy[-.]/.test(f));
|
|
1643
1647
|
checkPrereleaseTagTrigger(src, workflows, deploy, fail, warn);
|
|
1644
1648
|
checkReleaseAuto(src, workflows, cfg, warn);
|
|
1649
|
+
checkFastRouteDeploy(src, workflows, cfg, fail);
|
|
1645
1650
|
checkPrivateNpm(src, workflows, fail, warn);
|
|
1646
1651
|
|
|
1647
1652
|
const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
|
|
@@ -2537,7 +2542,8 @@ function releaseAutoFindings({ readFile, workflows, cfg }) {
|
|
|
2537
2542
|
const text = readFile(`.github/workflows/${wf}`);
|
|
2538
2543
|
if (!text || !RELEASE_AUTO_RUN.test(text)) continue;
|
|
2539
2544
|
const runsCut = /\brelease\s+cut\s+--auto\b/.test(text);
|
|
2540
|
-
|
|
2545
|
+
// #446: on deploy-tag-fast candidates are off by design — `cut --auto` tags the final itself.
|
|
2546
|
+
if (runsCut && effective && effective.candidates === "off" && effective.finalize !== "on-green-head") {
|
|
2541
2547
|
out.push(`${wf} runs \`colab release cut --auto\`, but the release rung leaves candidates off on this descriptor (${effective.route === null ? "no route" : `route ${effective.route}`}) — every run refuses; remove the workflow, or change exposure/deploy/release: deliberately (CONVENTIONS.md §6)`);
|
|
2542
2548
|
}
|
|
2543
2549
|
const publishesHere = /\bgh\s+release\s+create\b/.test(text) || /action-gh-release/.test(text) || /uses:\s*\.\/\.github\/workflows\//.test(text);
|
|
@@ -2561,6 +2567,42 @@ function checkReleaseAuto(src, workflows, cfg, warn) {
|
|
|
2561
2567
|
for (const text of releaseAutoFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
|
|
2562
2568
|
}
|
|
2563
2569
|
|
|
2570
|
+
// ---- route deploy-tag-fast: the final is deployed in the run that tags it (#446) ----------------
|
|
2571
|
+
// A tag pushed with GITHUB_TOKEN starts no `push: tags` workflow, so on this route the workflow that
|
|
2572
|
+
// runs `colab release cut --auto` must itself deploy what it tagged — templates/release-auto.yml's
|
|
2573
|
+
// `deploy` job reads the cut step's `final` output. Fail, not warn: without it every final reaches
|
|
2574
|
+
// the Release page and `stable` while production never moves, and nothing says so. Also fails the
|
|
2575
|
+
// template's deploy step left unedited (it fails every run by design, but the audit says why first).
|
|
2576
|
+
// What the audit cannot check is that the deploy really rolls back on a failed health check —
|
|
2577
|
+
// release.rollback: auto is the operator's statement of that, which is why the grant is required.
|
|
2578
|
+
const FAST_DEPLOY_CONSUMER = /outputs\.(final|deploy-tag)\b|\.final\s*\/\/|jq -r '\.final\b/;
|
|
2579
|
+
const FAST_DEPLOY_UNEDITED = /the deploy step of release-auto\.yml was never edited/;
|
|
2580
|
+
function fastRouteDeployFindings({ readFile, workflows, cfg }) {
|
|
2581
|
+
const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
|
|
2582
|
+
if (!effective || effective.finalize !== "on-green-head") return [];
|
|
2583
|
+
const cutters = (workflows || []).filter((wf) => {
|
|
2584
|
+
const t = readFile(`.github/workflows/${wf}`);
|
|
2585
|
+
return t && /\brelease\s+cut\s+--auto\b/.test(t);
|
|
2586
|
+
});
|
|
2587
|
+
if (!cutters.length) {
|
|
2588
|
+
return ["route: deploy-tag-fast but no workflow runs `colab release cut --auto` — nothing tags or deploys a final; copy templates/release-auto.yml (CONVENTIONS.md §6, A final on every green head)"];
|
|
2589
|
+
}
|
|
2590
|
+
const out = [];
|
|
2591
|
+
const deploying = cutters.filter((wf) => FAST_DEPLOY_CONSUMER.test(readFile(`.github/workflows/${wf}`)));
|
|
2592
|
+
if (!deploying.length) {
|
|
2593
|
+
out.push(`route: deploy-tag-fast, but ${cutters.join(", ")} runs \`colab release cut --auto\` and deploys nothing from its result — a tag pushed with GITHUB_TOKEN starts no \`push: tags\` run, so the final would never deploy; deploy in the same run (templates/release-auto.yml, job \`deploy\`)`);
|
|
2594
|
+
}
|
|
2595
|
+
for (const wf of deploying) {
|
|
2596
|
+
if (FAST_DEPLOY_UNEDITED.test(readFile(`.github/workflows/${wf}`))) {
|
|
2597
|
+
out.push(`route: deploy-tag-fast, but ${wf}'s deploy step is still the template's unedited placeholder — every final would be tagged and published but not deployed; replace it with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)`);
|
|
2598
|
+
}
|
|
2599
|
+
}
|
|
2600
|
+
return out;
|
|
2601
|
+
}
|
|
2602
|
+
function checkFastRouteDeploy(src, workflows, cfg, fail) {
|
|
2603
|
+
for (const text of fastRouteDeployFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) fail(text);
|
|
2604
|
+
}
|
|
2605
|
+
|
|
2564
2606
|
// ---- a private repo never publishes to public npm (#432) ---------------------
|
|
2565
2607
|
// Visibility is read from the GitHub API, and only when the repo has an npm surface at all (so an
|
|
2566
2608
|
// npm-free repo costs no API call). Unreadable / no remote → reported as a warn, never passed.
|
package/package.json
CHANGED
|
@@ -24,6 +24,8 @@
|
|
|
24
24
|
# any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
|
|
25
25
|
# project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
|
|
26
26
|
# comment above that job
|
|
27
|
+
# the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
|
|
28
|
+
# deploy-tag-fast only "DEPLOYING IN THIS RUN" below
|
|
27
29
|
#
|
|
28
30
|
# Every decision — whether a candidate is owed, which bump, whether the test period
|
|
29
31
|
# elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
|
|
@@ -77,6 +79,15 @@
|
|
|
77
79
|
# workflow pushes either — on a `deploy: tag` repo the final is a human act anyway, and
|
|
78
80
|
# finalize --auto only posts the command for it.
|
|
79
81
|
#
|
|
82
|
+
# DEPLOYING IN THIS RUN (deploy-tag-fast, #446). On a `deploy: tag` repo whose operator granted
|
|
83
|
+
# route `deploy-tag-fast` (release.final-grant + release.health-url + release.rollback: auto),
|
|
84
|
+
# `colab release cut --auto` tags the FINAL vX.Y.Z on every green main head — no candidate, no
|
|
85
|
+
# test period — and the `deploy` job below deploys that tag in this same run, then polls
|
|
86
|
+
# release.health-url until it reports the version. Its deploy step is an EDIT point: replace it
|
|
87
|
+
# with your deploy (it fails loudly until you do). On every other route the job is skipped and the
|
|
88
|
+
# run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
|
|
89
|
+
# tags a head that release.final-spacing held back sooner.
|
|
90
|
+
#
|
|
80
91
|
# IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
|
|
81
92
|
# pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
|
|
82
93
|
# checks recorded in the tag message) and — only on a repo granting unattended promotion — the
|
|
@@ -155,6 +166,9 @@ jobs:
|
|
|
155
166
|
npm-dir: ${{ steps.npm-target.outputs.dir }}
|
|
156
167
|
npm-gate: ${{ steps.npm-target.outputs.gate }}
|
|
157
168
|
npm-package: ${{ steps.npm-target.outputs.package }}
|
|
169
|
+
# What the deploy job below needs (#446) — empty unless this run tagged a deploy-tag-fast final.
|
|
170
|
+
deploy-tag: ${{ steps.cut.outputs.final }}
|
|
171
|
+
health-url: ${{ steps.cut.outputs.health-url }}
|
|
158
172
|
env:
|
|
159
173
|
GH_TOKEN: ${{ github.token }}
|
|
160
174
|
steps:
|
|
@@ -261,6 +275,12 @@ jobs:
|
|
|
261
275
|
TAG="$(jq -r '.tag' "$OUT")"
|
|
262
276
|
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
|
|
263
277
|
echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
278
|
+
# #446: on route deploy-tag-fast the cut IS the final, and the deploy job deploys it in
|
|
279
|
+
# this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow).
|
|
280
|
+
if [ "$(jq -r '.final // false' "$OUT")" = "true" ]; then
|
|
281
|
+
echo "final=$TAG" >> "$GITHUB_OUTPUT"
|
|
282
|
+
echo "health-url=$(jq -r '.deploy.healthUrl // ""' "$OUT")" >> "$GITHUB_OUTPUT"
|
|
283
|
+
fi
|
|
264
284
|
elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
|
|
265
285
|
echo "No-op: nothing owed, head already a candidate, inside a declared cadence window, or main's head is not a promotion." | tee -a "$GITHUB_STEP_SUMMARY"
|
|
266
286
|
elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
|
|
@@ -493,3 +513,60 @@ jobs:
|
|
|
493
513
|
gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
|
|
494
514
|
echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
495
515
|
done
|
|
516
|
+
|
|
517
|
+
# ---------------------------------------------------------------------------------------------
|
|
518
|
+
# deploy (#446) — route deploy-tag-fast only: deploys the final the release job just tagged, in
|
|
519
|
+
# this same run, then verifies it. Skipped on every other route (deploy-tag stays empty).
|
|
520
|
+
#
|
|
521
|
+
# Same run, never a tag-triggered deploy workflow: a tag pushed with GITHUB_TOKEN starts no
|
|
522
|
+
# `push: tags` run, so a separate deploy-on-tag workflow would never fire for this final.
|
|
523
|
+
#
|
|
524
|
+
# The health check is the handbook's half of the "health-gated deploy with automatic rollback"
|
|
525
|
+
# the route requires: it fails this job when release.health-url does not report the version in
|
|
526
|
+
# time. The ROLLBACK is your deploy's own (release.rollback: auto is your statement that it has
|
|
527
|
+
# one) — this job does not roll anything back. A failed deploy leaves the tag standing and this
|
|
528
|
+
# run red; fix forward, or re-run the failed job to deploy the same tag again.
|
|
529
|
+
deploy:
|
|
530
|
+
name: Deploy the final (deploy-tag-fast)
|
|
531
|
+
needs: release
|
|
532
|
+
if: needs.release.outputs.deploy-tag != ''
|
|
533
|
+
runs-on: ubuntu-latest # EDIT: the runner your deploy needs (self-hosted label, etc.).
|
|
534
|
+
environment: production # EDIT: the GitHub environment holding your deploy secrets, or remove.
|
|
535
|
+
permissions:
|
|
536
|
+
contents: read # check out the tag
|
|
537
|
+
env:
|
|
538
|
+
TAG: ${{ needs.release.outputs.deploy-tag }}
|
|
539
|
+
HEALTH_URL: ${{ needs.release.outputs.health-url }}
|
|
540
|
+
HEALTH_TIMEOUT_SECONDS: "600" # EDIT: how long the new version may take to report itself.
|
|
541
|
+
steps:
|
|
542
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
543
|
+
with:
|
|
544
|
+
ref: refs/tags/${{ needs.release.outputs.deploy-tag }}
|
|
545
|
+
persist-credentials: false # nothing here pushes
|
|
546
|
+
|
|
547
|
+
# EDIT: replace this step's body with your deploy of "$TAG" (an image push + rollout, an
|
|
548
|
+
# SSH script, a platform CLI). It must roll back by itself when the new version fails its
|
|
549
|
+
# health check — that is what release.rollback: auto declares. Until edited it fails, so a
|
|
550
|
+
# final is never reported deployed when nothing deployed it.
|
|
551
|
+
- name: Deploy the final (EDIT)
|
|
552
|
+
run: |
|
|
553
|
+
set -euo pipefail
|
|
554
|
+
echo "::error::the deploy step of release-auto.yml was never edited — $TAG is tagged and published but NOT deployed. Replace this step with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)."
|
|
555
|
+
exit 1
|
|
556
|
+
|
|
557
|
+
- name: Verify the health endpoint reports the final
|
|
558
|
+
run: |
|
|
559
|
+
set -uo pipefail
|
|
560
|
+
VERSION="${TAG#v}"
|
|
561
|
+
DEADLINE=$(( $(date +%s) + HEALTH_TIMEOUT_SECONDS ))
|
|
562
|
+
while :; do
|
|
563
|
+
BODY="$(curl -fsS --max-time 10 "$HEALTH_URL" 2> /dev/null || true)"
|
|
564
|
+
case "$BODY" in
|
|
565
|
+
*"$VERSION"*) echo "$HEALTH_URL reports $VERSION — $TAG is live" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0 ;;
|
|
566
|
+
esac
|
|
567
|
+
if [ "$(date +%s)" -ge "$DEADLINE" ]; then
|
|
568
|
+
echo "::error::$HEALTH_URL did not report $VERSION within ${HEALTH_TIMEOUT_SECONDS}s — the deploy's own rollback should have restored the previous version; $TAG stays tagged"
|
|
569
|
+
exit 1
|
|
570
|
+
fi
|
|
571
|
+
sleep 10
|
|
572
|
+
done
|
package/tools/colab
CHANGED
|
@@ -1235,6 +1235,20 @@ Refuses, naming each failed condition (all are reported, not just the first):
|
|
|
1235
1235
|
There the bump reads the promoted commits (main's merge subject is skipped),
|
|
1236
1236
|
and a switch-removal child counts when its Closes #N was promoted.
|
|
1237
1237
|
|
|
1238
|
+
Route deploy-tag-fast (#446) — a deploy: tag repo with the operator's grant and a declared health gate:
|
|
1239
|
+
--auto tags the FINAL vX.Y.Z on main's green head — no candidate, no test period — publishes it as
|
|
1240
|
+
the latest GitHub Release, moves the stable channel, and prints final/deploy in --json so the
|
|
1241
|
+
release workflow's deploy job deploys it in the same run. Without --auto it refuses: a final cut by
|
|
1242
|
+
hand would reach production with no deploy job behind it. Five more conditions there:
|
|
1243
|
+
spacing release.final-spacing (default and floor 1h) since the newest final — inside
|
|
1244
|
+
it the run is a NO-OP; the first run after it tags main's head
|
|
1245
|
+
already-final main's head already carries a final — a NO-OP
|
|
1246
|
+
final-grant release.final-grant's decision still resolves (recorded, trusted, not reopened)
|
|
1247
|
+
release-hold an open issue carries the release-hold label (a human veto)
|
|
1248
|
+
migration-grant a migration since the last final with no grant on the version's tracking
|
|
1249
|
+
issue — refused; a non-dry run opens "release: vX.Y.Z" if needed and posts the
|
|
1250
|
+
one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z)
|
|
1251
|
+
|
|
1238
1252
|
The bump (without --auto) is release-status's semverSuggestion since the last final tag (candidates skipped): fix ->
|
|
1239
1253
|
patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
|
|
1240
1254
|
--bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
|
|
@@ -1441,6 +1455,75 @@ function measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trun
|
|
|
1441
1455
|
return { signals, migration: (v) => releaseCut.parseMigrationSection(migrationText, v) };
|
|
1442
1456
|
}
|
|
1443
1457
|
|
|
1458
|
+
/** #446: every final `vX.Y.Z` tag as [{ name, date }] — what release.final-spacing counts. A human's final counts too. */
|
|
1459
|
+
function finalTags(repoAbs) {
|
|
1460
|
+
const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(creatordate:iso-strict)'], repoAbs);
|
|
1461
|
+
return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
|
|
1462
|
+
.filter(([name]) => releaseCut.parseVersion(name)).map(([name, date]) => ({ name, date }));
|
|
1463
|
+
}
|
|
1464
|
+
|
|
1465
|
+
/**
|
|
1466
|
+
* #446: what route deploy-tag-fast keeps in place of a test period, measured — the operator's grant
|
|
1467
|
+
* (the #441 reader, against trunk's trust-humans), the repo-wide release-hold veto, every migration
|
|
1468
|
+
* since the last final against a grant on the computed version's tracking issue, and the spacing
|
|
1469
|
+
* since the newest final. The version is computed here only to find that tracking issue; decide()
|
|
1470
|
+
* computes it again from the same inputs, so the two cannot disagree.
|
|
1471
|
+
*/
|
|
1472
|
+
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths }) {
|
|
1473
|
+
const grantDecl = policy.effective.finalGrant;
|
|
1474
|
+
const trust = trustAt(repoAbs, `${remote}/main`);
|
|
1475
|
+
const finalGrant = isGhUsable(repoAbs)
|
|
1476
|
+
? releasePolicy.finalGrantVerdict(git.ghIssueView(repoAbs, grantDecl.issue, ['state', 'labels', 'comments']), { issue: grantDecl.issue, trust })
|
|
1477
|
+
: { ok: false, ruledBy: null, detail: `release.final-grant #${grantDecl.issue} could not be read: gh not usable (${ghUnusableWhy(repoAbs)})` };
|
|
1478
|
+
const holds = releaseCut.holdsVerdict(issues);
|
|
1479
|
+
let tracking = null;
|
|
1480
|
+
let grant = null;
|
|
1481
|
+
const v = auto ? releaseCut.decideAutoVersion({ lastFinal, signals: auto.signals, migration: auto.migration, tags }) : null;
|
|
1482
|
+
if (v && v.ok && issues) {
|
|
1483
|
+
const open = issues.filter((i) => String(i.state || '').toUpperCase() === 'OPEN' && releaseFinalize.parseReleaseMarker(i.body) === v.version);
|
|
1484
|
+
if (open.length) tracking = { number: open[0].number };
|
|
1485
|
+
}
|
|
1486
|
+
if (paths && paths.length) {
|
|
1487
|
+
grant = tracking
|
|
1488
|
+
? migrationGrant.evaluateIssue(git.ghIssueView(repoAbs, tracking.number, ['state', 'labels', 'comments']), v.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
|
|
1489
|
+
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
1490
|
+
if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
|
|
1491
|
+
}
|
|
1492
|
+
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
|
|
1493
|
+
const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
|
|
1494
|
+
return { finalGrant, holds, migrations, spacing, tracking };
|
|
1495
|
+
}
|
|
1496
|
+
|
|
1497
|
+
/** Post `text` on issue `num` once — idempotent by release-finalize's event marker. */
|
|
1498
|
+
function commentOnce(repoAbs, num, fields, text) {
|
|
1499
|
+
const view = git.ghIssueView(repoAbs, num, ['comments']);
|
|
1500
|
+
if (view && releaseFinalize.hasEvent(view.comments, fields)) return;
|
|
1501
|
+
const r = git.ghIssueComment(repoAbs, num, `${releaseFinalize.eventMarker(fields)}\n${text}`);
|
|
1502
|
+
if (!r.ok) warn(`could not comment on #${num}: ${String(r.stderr || '').split('\n')[0]}`);
|
|
1503
|
+
}
|
|
1504
|
+
|
|
1505
|
+
/**
|
|
1506
|
+
* #426: one "Released in vX.Y.Z" comment on every issue the version carries — the closing references
|
|
1507
|
+
* in (previous final, sha], minus `exclude` (the release tracking issues). Idempotent by event marker.
|
|
1508
|
+
* Shared by `release finalize` and, on route deploy-tag-fast (#446), `release cut`.
|
|
1509
|
+
*/
|
|
1510
|
+
function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
|
|
1511
|
+
const prev = releaseFinalize.previousFinal(tagNames, version);
|
|
1512
|
+
if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
|
|
1513
|
+
const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
|
|
1514
|
+
if (!log.ok) { warn(`could not read ${prev}..${shortSha(sha)} — no issue told it was released in ${version}`); return { range: `${prev}..${version}`, issues: [], posted: [], skipped: [], detail: 'git log failed' }; }
|
|
1515
|
+
const nums = releaseFinalize.carriedIssues(log.stdout.split('\0'), { exclude });
|
|
1516
|
+
const posted = []; const skipped = [];
|
|
1517
|
+
for (const n of nums) {
|
|
1518
|
+
const view = git.ghIssueView(repoAbs, n, ['comments']);
|
|
1519
|
+
if (!view) { skipped.push(n); continue; }
|
|
1520
|
+
if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
|
|
1521
|
+
const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
|
|
1522
|
+
if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
|
|
1523
|
+
}
|
|
1524
|
+
return { range: `${prev}..${version}`, issues: nums, posted, skipped };
|
|
1525
|
+
}
|
|
1526
|
+
|
|
1444
1527
|
function cmdReleaseCut(argv) {
|
|
1445
1528
|
const opts = parseArgs(argv, {
|
|
1446
1529
|
values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
|
|
@@ -1485,7 +1568,7 @@ function cmdReleaseCut(argv) {
|
|
|
1485
1568
|
const tags = lines(git.git(['tag', '--list'], repoAbs));
|
|
1486
1569
|
const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs));
|
|
1487
1570
|
|
|
1488
|
-
const { ci, suite, schema, switches, issues } = measureCandidateConditions(repoAbs, {
|
|
1571
|
+
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
|
|
1489
1572
|
sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
|
|
1490
1573
|
});
|
|
1491
1574
|
const { manifests, ancestry } = measurePreTag(repoAbs, sha, `${remote}/main`); // #424
|
|
@@ -1497,9 +1580,17 @@ function cmdReleaseCut(argv) {
|
|
|
1497
1580
|
auto = { signals, migration, cadence, promotion: offTrunk ? measurePromotion(repoAbs, { sha, trunk, remote, fetched: trunkFetch }) : null };
|
|
1498
1581
|
}
|
|
1499
1582
|
|
|
1583
|
+
// #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
|
|
1584
|
+
// measured only there, so every candidate route's run is what it was.
|
|
1585
|
+
const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
|
|
1586
|
+
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince }) : {};
|
|
1587
|
+
if (fast && auto) auto.spacing = fastFacts.spacing;
|
|
1588
|
+
|
|
1500
1589
|
const verdict = releaseCut.decide({
|
|
1501
1590
|
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
|
|
1502
1591
|
override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
|
|
1592
|
+
finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations,
|
|
1593
|
+
trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
|
|
1503
1594
|
});
|
|
1504
1595
|
|
|
1505
1596
|
let created = false;
|
|
@@ -1514,19 +1605,54 @@ function cmdReleaseCut(argv) {
|
|
|
1514
1605
|
throw new UserError(`git push ${remote} ${verdict.tag} failed — the local tag was deleted again, nothing is cut (${(push.stderr || '').split('\n')[0]})`);
|
|
1515
1606
|
}
|
|
1516
1607
|
created = true;
|
|
1517
|
-
published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message });
|
|
1608
|
+
published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message, final: !!verdict.final });
|
|
1518
1609
|
}
|
|
1519
1610
|
// #445: the `next` channel names the newest candidate — fast-forwarded in the run that pushed it.
|
|
1520
1611
|
// Best-effort like the pre-release: the tag already stands, so a channel that cannot move is reported.
|
|
1612
|
+
// #446: a fast-route final moves `stable` instead — it is the newest final, and there is no candidate.
|
|
1521
1613
|
const channel = verdict.ok && verdict.tag
|
|
1522
|
-
? releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
|
|
1614
|
+
? releaseChannel.moveChannel(repoAbs, { remote, channel: verdict.final ? releaseChannel.CHANNELS.stable : releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
|
|
1523
1615
|
: null;
|
|
1524
1616
|
|
|
1617
|
+
// #446: the fast route's own writes. A final: every issue it carries hears which version has it, and
|
|
1618
|
+
// an open tracking record for the version is closed. An ungranted migration: the hand-off is posted
|
|
1619
|
+
// on the version's tracking issue (opened if there is none), for a human to grant.
|
|
1620
|
+
let announced = null;
|
|
1621
|
+
let handoff = verdict.handoff || null;
|
|
1622
|
+
if (fast && !opts.dry) {
|
|
1623
|
+
if (created) {
|
|
1624
|
+
const exclude = (issues || []).filter((i) => releaseFinalize.parseReleaseMarker(i.body)).map((i) => i.number);
|
|
1625
|
+
announced = announceCarried(repoAbs, { tagNames: [...tags, verdict.tag], exclude, version: verdict.tag, sha });
|
|
1626
|
+
if (fastFacts.tracking) {
|
|
1627
|
+
commentOnce(repoAbs, fastFacts.tracking.number, { state: 'finalized', tag: verdict.tag }, `**${verdict.tag}** tagged final on \`${shortSha(sha)}\` by route deploy-tag-fast — the release workflow deploys it in this run.`);
|
|
1628
|
+
const r = spawnSync('gh', ['issue', 'close', String(fastFacts.tracking.number)], { cwd: repoAbs, encoding: 'utf8' });
|
|
1629
|
+
if (r.status !== 0) warn(`could not close #${fastFacts.tracking.number}: ${String(r.stderr || '').split('\n')[0]}`);
|
|
1630
|
+
}
|
|
1631
|
+
} else if (handoff && verdict.version) {
|
|
1632
|
+
let num = fastFacts.tracking ? fastFacts.tracking.number : null;
|
|
1633
|
+
if (!num && issues !== null) {
|
|
1634
|
+
const c = spawnSync('gh', ['issue', 'create', '--title', releaseFinalize.trackingTitle(verdict.version), '--body', releaseCut.handoffTrackingBody(verdict.version)], { cwd: repoAbs, encoding: 'utf8' });
|
|
1635
|
+
const m = c.status === 0 ? /\/issues\/([0-9]+)/.exec(c.stdout || '') : null;
|
|
1636
|
+
if (m) num = Number(m[1]);
|
|
1637
|
+
else warn(`could not open the tracking issue for ${verdict.version} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'}) — the hand-off is printed here only`);
|
|
1638
|
+
}
|
|
1639
|
+
if (num) {
|
|
1640
|
+
handoff = releaseCut.migrationHandoff(num, verdict.version);
|
|
1641
|
+
commentOnce(repoAbs, num, { state: 'migration-handoff', version: verdict.version },
|
|
1642
|
+
`**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\``);
|
|
1643
|
+
}
|
|
1644
|
+
}
|
|
1645
|
+
}
|
|
1646
|
+
|
|
1525
1647
|
if (opts.json) {
|
|
1526
1648
|
print(JSON.stringify({
|
|
1527
1649
|
repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1528
1650
|
ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
|
|
1529
1651
|
overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
|
|
1652
|
+
// #446: present on every route, so the workflow reads one shape — final only on deploy-tag-fast.
|
|
1653
|
+
final: !!verdict.final,
|
|
1654
|
+
deploy: verdict.final && verdict.healthGate ? { healthUrl: verdict.healthGate.url, rollback: verdict.healthGate.rollback } : null,
|
|
1655
|
+
grant: verdict.grant || null, handoff, ...(fast ? { announced } : {}),
|
|
1530
1656
|
}, null, 2));
|
|
1531
1657
|
return verdict.ok || verdict.noop ? 0 : 1;
|
|
1532
1658
|
}
|
|
@@ -1540,14 +1666,25 @@ function cmdReleaseCut(argv) {
|
|
|
1540
1666
|
for (const c of verdict.checks) print(` ${c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
|
|
1541
1667
|
print('');
|
|
1542
1668
|
if (verdict.noop) {
|
|
1543
|
-
print(
|
|
1669
|
+
print(fast
|
|
1670
|
+
? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
|
|
1671
|
+
: '· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
|
|
1544
1672
|
return 0;
|
|
1545
1673
|
}
|
|
1546
1674
|
if (!verdict.ok) {
|
|
1547
1675
|
print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
|
|
1676
|
+
if (handoff) print(`\nA migration rides this release. The one command, for a human to run:\n ${handoff}`);
|
|
1548
1677
|
return 1;
|
|
1549
1678
|
}
|
|
1550
|
-
if (
|
|
1679
|
+
if (verdict.final) {
|
|
1680
|
+
if (opts.dry) print(`[--dry] would tag the final ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub Release and move the stable channel — the workflow's deploy job would then deploy it and check ${verdict.healthGate.url}. Nothing created.`);
|
|
1681
|
+
else {
|
|
1682
|
+
print(`✓ tagged the final ${verdict.tag} on ${at} and pushed it to ${remote} — route deploy-tag-fast, by the operator's grant (decision #${verdict.grant.issue}); the release workflow deploys it in this run.`);
|
|
1683
|
+
if (published && published.ok) print(`✓ ${published.detail}`);
|
|
1684
|
+
else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --latest`);
|
|
1685
|
+
if (announced && announced.issues.length) print(`released in ${verdict.tag}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'}`);
|
|
1686
|
+
}
|
|
1687
|
+
} else if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
|
|
1551
1688
|
else {
|
|
1552
1689
|
print(`✓ cut ${verdict.tag} on ${at} and pushed it to ${remote} — a candidate, not a release; finalizing it is the release skill's.`);
|
|
1553
1690
|
if (published && published.ok) print(`✓ ${published.detail}`);
|
|
@@ -1566,8 +1703,10 @@ function cmdReleaseCut(argv) {
|
|
|
1566
1703
|
* workflow raced us) is left alone. Best-effort: the tag is already on origin, so a failure here is
|
|
1567
1704
|
* reported, never a reason to undo the cut.
|
|
1568
1705
|
*/
|
|
1569
|
-
function publishPrerelease(repoAbs, { tag, lastFinal, message }) {
|
|
1570
|
-
|
|
1706
|
+
function publishPrerelease(repoAbs, { tag, lastFinal, message, final = false }) {
|
|
1707
|
+
// #446: a deploy-tag-fast final is published as a full release, marked latest.
|
|
1708
|
+
const kind = final ? 'release' : 'pre-release';
|
|
1709
|
+
if (!isGhUsable(repoAbs)) return { ok: false, detail: `${kind} NOT published: gh not usable (${ghUnusableWhy(repoAbs)})` };
|
|
1571
1710
|
const view = spawnSync('gh', ['release', 'view', tag, '--json', 'tagName'], { cwd: repoAbs, encoding: 'utf8' });
|
|
1572
1711
|
if (view.status === 0) return { ok: true, detail: `${tag} already has a GitHub Release — left as it is` };
|
|
1573
1712
|
let notes;
|
|
@@ -1576,13 +1715,13 @@ function publishPrerelease(repoAbs, { tag, lastFinal, message }) {
|
|
|
1576
1715
|
} catch (e) {
|
|
1577
1716
|
notes = `## ${tag}\n\n(release notes unavailable: ${e.message})\n`;
|
|
1578
1717
|
}
|
|
1579
|
-
notes += `\n### Candidate record\n\n\`\`\`\n${message}\`\`\`\n`;
|
|
1718
|
+
notes += `\n### ${final ? 'Release' : 'Candidate'} record\n\n\`\`\`\n${message}\`\`\`\n`;
|
|
1580
1719
|
const file = path.join(os.tmpdir(), `colab-release-notes-${process.pid}-${tag}.md`);
|
|
1581
1720
|
fs.writeFileSync(file, notes);
|
|
1582
1721
|
try {
|
|
1583
|
-
const r = spawnSync('gh', releaseCut.prereleaseArgs(tag, file), { cwd: repoAbs, encoding: 'utf8' });
|
|
1584
|
-
if (r.status !== 0) return { ok: false, detail:
|
|
1585
|
-
return { ok: true, detail: `published the GitHub
|
|
1722
|
+
const r = spawnSync('gh', final ? releaseCut.finalReleaseArgs(tag, file) : releaseCut.prereleaseArgs(tag, file), { cwd: repoAbs, encoding: 'utf8' });
|
|
1723
|
+
if (r.status !== 0) return { ok: false, detail: `${kind} NOT published: gh release create ${tag} failed (${(r.stderr || '').split('\n')[0] || r.status})` };
|
|
1724
|
+
return { ok: true, detail: `published the GitHub ${kind} ${tag}` };
|
|
1586
1725
|
} finally {
|
|
1587
1726
|
try { fs.unlinkSync(file); } catch (_) { /* best-effort */ }
|
|
1588
1727
|
}
|
|
@@ -1877,22 +2016,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
1877
2016
|
// #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
|
|
1878
2017
|
// carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
|
|
1879
2018
|
let announced = null;
|
|
1880
|
-
const announceRelease = (version, sha) => {
|
|
1881
|
-
const prev = releaseFinalize.previousFinal(tagNames, version);
|
|
1882
|
-
if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
|
|
1883
|
-
const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
|
|
1884
|
-
if (!log.ok) { warn(`could not read ${prev}..${shortSha(sha)} — no issue told it was released in ${version}`); return { range: `${prev}..${version}`, issues: [], posted: [], skipped: [], detail: 'git log failed' }; }
|
|
1885
|
-
const nums = releaseFinalize.carriedIssues(log.stdout.split('\0'), { exclude: records.map((r) => r.number) });
|
|
1886
|
-
const posted = []; const skipped = [];
|
|
1887
|
-
for (const n of nums) {
|
|
1888
|
-
const view = git.ghIssueView(repoAbs, n, ['comments']);
|
|
1889
|
-
if (!view) { skipped.push(n); continue; }
|
|
1890
|
-
if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
|
|
1891
|
-
const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
|
|
1892
|
-
if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
|
|
1893
|
-
}
|
|
1894
|
-
return { range: `${prev}..${version}`, issues: nums, posted, skipped };
|
|
1895
|
-
};
|
|
2019
|
+
const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
|
|
1896
2020
|
if (!opts.dry) {
|
|
1897
2021
|
if (verdict.state === 'finalized') {
|
|
1898
2022
|
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)' : ''}`;
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -46,8 +46,22 @@
|
|
|
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');
|
|
@@ -64,11 +78,23 @@ const BUMPS = Object.freeze(['patch', 'minor']);
|
|
|
64
78
|
const RELEASE_BRANCH = 'main';
|
|
65
79
|
|
|
66
80
|
const CONDITIONS = Object.freeze([
|
|
67
|
-
'release-policy', 'cadence', 'promotion', 'prerelease-trigger', 'version', 'already-candidate',
|
|
81
|
+
'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
68
82
|
...releaseTag.PRE_TAG_CONDITIONS,
|
|
69
83
|
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
84
|
+
'final-grant', 'release-hold', 'migration-grant',
|
|
70
85
|
]);
|
|
71
86
|
|
|
87
|
+
/** #446: the conditions only route deploy-tag-fast reports. */
|
|
88
|
+
const FAST_CONDITIONS = Object.freeze(['spacing', 'already-final', 'final-grant', 'release-hold', 'migration-grant']);
|
|
89
|
+
|
|
90
|
+
/** #446: the label a human puts on an issue to veto a release — the same one release-finalize reads. */
|
|
91
|
+
const HOLD_LABEL = 'release-hold';
|
|
92
|
+
|
|
93
|
+
/** #446: is this policy the fast route, where `cut --auto` tags the final itself? */
|
|
94
|
+
function isFastRoute(policy) {
|
|
95
|
+
return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
|
|
96
|
+
}
|
|
97
|
+
|
|
72
98
|
/** The file a major's migration section is read from, at the candidate commit (#422). */
|
|
73
99
|
const MIGRATION_FILE = 'MIGRATION.md';
|
|
74
100
|
|
|
@@ -390,6 +416,45 @@ function cadenceVerdict({ candidates, perDay, now }) {
|
|
|
390
416
|
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
417
|
}
|
|
392
418
|
|
|
419
|
+
// ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* Finals at least `spacingHours` apart. `finals` is [{ name, date }] for every final tag (tagger
|
|
423
|
+
* date) — a human's final counts as much as an automatic one. Returns { ok, detail, nextAt }; not ok
|
|
424
|
+
* is a NO-OP for the caller, never a refusal, so the first run after the window tags main's head.
|
|
425
|
+
*/
|
|
426
|
+
function spacingVerdict({ finals, spacingHours, now }) {
|
|
427
|
+
if (!spacingHours) return { ok: true, detail: 'no final spacing on this route', nextAt: null };
|
|
428
|
+
const nowMs = Date.parse(now);
|
|
429
|
+
const dated = (finals || []).map((f) => ({ ...f, ms: Date.parse(f.date) }))
|
|
430
|
+
.filter((f) => !Number.isNaN(f.ms) && f.ms <= nowMs).sort((a, b) => a.ms - b.ms);
|
|
431
|
+
if (!dated.length) return { ok: true, detail: 'no earlier final to space from', nextAt: null };
|
|
432
|
+
const last = dated[dated.length - 1];
|
|
433
|
+
const nextMs = last.ms + spacingHours * 3600000;
|
|
434
|
+
if (nowMs >= nextMs) return { ok: true, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()}, spacing ${spacingHours}h`, nextAt: null };
|
|
435
|
+
const nextAt = new Date(nextMs).toISOString();
|
|
436
|
+
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 };
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
/**
|
|
440
|
+
* The human veto, repo-wide: `issues` is the open-issue list (null = unread — never "no hold").
|
|
441
|
+
* Any open issue carrying `release-hold` holds the next final; the fast route has no candidate issue
|
|
442
|
+
* to put the label on, so a human may put it on any issue, and only a human removes it.
|
|
443
|
+
*/
|
|
444
|
+
function holdsVerdict(issues) {
|
|
445
|
+
if (issues === null || issues === undefined) return { ok: false, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
|
|
446
|
+
const held = issues.filter((i) => i && (!i.state || String(i.state).toUpperCase() === 'OPEN')
|
|
447
|
+
&& (i.labels || []).some((l) => (l && typeof l === 'object' ? l.name : l) === HOLD_LABEL)).map((i) => i.number);
|
|
448
|
+
return held.length
|
|
449
|
+
? { 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` }
|
|
450
|
+
: { ok: true, detail: `no open issue carries ${HOLD_LABEL}` };
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
/** The command a human runs to let a migration ride an automatic final on the fast route. */
|
|
454
|
+
function migrationHandoff(tracking, version) {
|
|
455
|
+
return `COLAB_HUMAN=1 colab migration-grant ${tracking || '<tracking issue>'} --branch ${version}`;
|
|
456
|
+
}
|
|
457
|
+
|
|
393
458
|
// ---- #443: the newest candidate names trunk's head -------------------------------------------
|
|
394
459
|
|
|
395
460
|
/** Events that run DOWNSTREAM of the suite (the release workflow itself) — never part of "head is green". */
|
|
@@ -452,6 +517,28 @@ function prereleaseArgs(tag, notesFile) {
|
|
|
452
517
|
return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--prerelease', '--latest=false'];
|
|
453
518
|
}
|
|
454
519
|
|
|
520
|
+
/** #446: a deploy-tag-fast final's GitHub Release — a full release, marked latest. */
|
|
521
|
+
function finalReleaseArgs(tag, notesFile) {
|
|
522
|
+
return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--latest'];
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* #446: the tracking issue a fast-route migration hand-off opens. Same marker as release-finalize's
|
|
527
|
+
* (`<!-- colab:release version=… -->`), so every reader finds it; the text says what is owed here —
|
|
528
|
+
* a migration grant, not a candidate's test period.
|
|
529
|
+
*/
|
|
530
|
+
function handoffTrackingBody(version) {
|
|
531
|
+
return [
|
|
532
|
+
`<!-- colab:release version=${version} -->`,
|
|
533
|
+
'',
|
|
534
|
+
`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.`,
|
|
535
|
+
'',
|
|
536
|
+
'- 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.',
|
|
537
|
+
`- **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}.`,
|
|
538
|
+
`- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
|
|
539
|
+
].join('\n') + '\n';
|
|
540
|
+
}
|
|
541
|
+
|
|
455
542
|
// ---- §6 condition 2: the full suite ------------------------------------------------------------
|
|
456
543
|
|
|
457
544
|
/**
|
|
@@ -709,9 +796,14 @@ function decide(facts) {
|
|
|
709
796
|
const add = (condition, ok, detail) => checks.push({ condition, ok: !!ok, detail });
|
|
710
797
|
|
|
711
798
|
const p = f.policy;
|
|
799
|
+
const fast = isFastRoute(p) && !(p.findings && p.findings.length);
|
|
712
800
|
if (!p) add('release-policy', false, 'no release policy was evaluated');
|
|
713
801
|
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 (
|
|
802
|
+
else if (fast && !f.auto) {
|
|
803
|
+
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');
|
|
804
|
+
} else if (fast) {
|
|
805
|
+
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`);
|
|
806
|
+
} else if (p.effective.candidates !== 'auto') {
|
|
715
807
|
const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
|
|
716
808
|
add('release-policy', false, narrowed
|
|
717
809
|
? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
|
|
@@ -726,6 +818,11 @@ function decide(facts) {
|
|
|
726
818
|
const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
|
|
727
819
|
add('cadence', cad.ok, cad.detail);
|
|
728
820
|
if (!cad.ok) noop = !!f.auto.cadence;
|
|
821
|
+
if (fast) {
|
|
822
|
+
const sp = f.auto.spacing || { ok: false, detail: 'final spacing not measured' };
|
|
823
|
+
add('spacing', sp.ok, sp.detail);
|
|
824
|
+
if (!sp.ok && f.auto.spacing) noop = true;
|
|
825
|
+
}
|
|
729
826
|
// #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
|
|
730
827
|
const pr = f.auto.promotion;
|
|
731
828
|
if (pr) {
|
|
@@ -747,7 +844,16 @@ function decide(facts) {
|
|
|
747
844
|
|
|
748
845
|
let tag = null;
|
|
749
846
|
let derivable = [];
|
|
750
|
-
if (v.ok) {
|
|
847
|
+
if (v.ok && fast) {
|
|
848
|
+
const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
|
|
849
|
+
if (finalHere.length) {
|
|
850
|
+
add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
|
|
851
|
+
if (f.auto) noop = true;
|
|
852
|
+
} else {
|
|
853
|
+
tag = v.version;
|
|
854
|
+
add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
|
|
855
|
+
}
|
|
856
|
+
} else if (v.ok) {
|
|
751
857
|
const here = candidateNumbers(f.tagsAtSha || [], v.version);
|
|
752
858
|
if (here.length) {
|
|
753
859
|
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`);
|
|
@@ -776,6 +882,20 @@ function decide(facts) {
|
|
|
776
882
|
else add(condition, verdict.ok, verdict.detail);
|
|
777
883
|
}
|
|
778
884
|
|
|
885
|
+
// #446: what the fast route keeps in place of the test period it does not have.
|
|
886
|
+
let handoff = null;
|
|
887
|
+
let grant = null;
|
|
888
|
+
if (fast) {
|
|
889
|
+
const g = f.finalGrant || { ok: false, detail: `release.final-grant #${p.effective.finalGrant.issue} was not resolved — an unresolved grant is not a grant` };
|
|
890
|
+
add('final-grant', g.ok, g.detail);
|
|
891
|
+
if (g.ok) grant = { issue: p.effective.finalGrant.issue, ruledBy: g.ruledBy || null };
|
|
892
|
+
const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
|
|
893
|
+
add('release-hold', h.ok, h.detail);
|
|
894
|
+
const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
|
|
895
|
+
add('migration-grant', mig.ok, mig.detail);
|
|
896
|
+
if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
|
|
897
|
+
}
|
|
898
|
+
|
|
779
899
|
const refusals = checks.filter((c) => !c.ok);
|
|
780
900
|
const ok = refusals.length === 0 && !!tag;
|
|
781
901
|
return {
|
|
@@ -783,6 +903,8 @@ function decide(facts) {
|
|
|
783
903
|
bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
|
|
784
904
|
signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
|
|
785
905
|
derivable,
|
|
906
|
+
final: fast, grant, handoff,
|
|
907
|
+
healthGate: fast ? p.effective.healthGate : null,
|
|
786
908
|
};
|
|
787
909
|
}
|
|
788
910
|
|
|
@@ -793,8 +915,11 @@ function versionSourceOf(policy) {
|
|
|
793
915
|
|
|
794
916
|
/** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
|
|
795
917
|
function tagMessage(verdict, { sha, lastFinal }) {
|
|
918
|
+
// #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
|
|
919
|
+
// reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
|
|
920
|
+
const fast = !!verdict.final;
|
|
796
921
|
const lines = [
|
|
797
|
-
`${verdict.tag} — release candidate (colab release cut)`,
|
|
922
|
+
fast ? `${verdict.tag} — release (colab release cut, deploy-tag-fast)` : `${verdict.tag} — release candidate (colab release cut)`,
|
|
798
923
|
'',
|
|
799
924
|
`Commit: ${sha}`,
|
|
800
925
|
`Since: ${lastFinal}`,
|
|
@@ -802,21 +927,24 @@ function tagMessage(verdict, { sha, lastFinal }) {
|
|
|
802
927
|
'',
|
|
803
928
|
...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
|
|
804
929
|
...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
|
|
930
|
+
...(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)`] : []),
|
|
931
|
+
...(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`, ''] : []),
|
|
805
932
|
...(verdict.derivable && verdict.derivable.length ? [`Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
|
|
806
933
|
'Conditions (CONVENTIONS.md §6):',
|
|
807
934
|
...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
|
|
808
935
|
'',
|
|
809
|
-
'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
|
|
936
|
+
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
937
|
];
|
|
811
938
|
return lines.join('\n') + '\n';
|
|
812
939
|
}
|
|
813
940
|
|
|
814
941
|
module.exports = {
|
|
815
|
-
CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH,
|
|
942
|
+
CONDITIONS, FAST_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
943
|
+
isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
816
944
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
817
945
|
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
818
946
|
fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
|
|
819
947
|
parseSwitchMarkers, switchVerdict,
|
|
820
948
|
promotionVerdict, decide, tagMessage, versionSourceOf,
|
|
821
|
-
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs,
|
|
949
|
+
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
|
|
822
950
|
};
|
|
@@ -397,6 +397,13 @@ function decide(facts) {
|
|
|
397
397
|
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
398
|
else add('release-policy', true, `${p.derived.axis} (${row}): final ${finalMode}, test period ${p.effective.testPeriodDays}d`);
|
|
399
399
|
if (!checks[0].ok) return out('refused');
|
|
400
|
+
// #446: route deploy-tag-fast tags its finals in `release cut --auto`, with no candidate. A leftover
|
|
401
|
+
// candidate from an earlier route is superseded by the next final — never finalized here, where the
|
|
402
|
+
// grant would otherwise finalize an old -rc days after the operator chose the fast route.
|
|
403
|
+
if (p.effective.finalize === 'on-green-head') {
|
|
404
|
+
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');
|
|
405
|
+
return out('no-candidate');
|
|
406
|
+
}
|
|
400
407
|
|
|
401
408
|
const s = f.selection || { kind: 'none', detail: 'no candidate selected' };
|
|
402
409
|
if (s.kind === 'none') { add('candidate', false, s.detail); return out('no-candidate'); }
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* declare to CHOOSE a route its row permits and to NARROW it:
|
|
9
9
|
*
|
|
10
10
|
* release:
|
|
11
|
-
* route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | live
|
|
11
|
+
* route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
|
|
12
12
|
* candidates: auto # auto | off
|
|
13
13
|
* candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
|
|
14
14
|
* test-period: 3d # <N>d, never below the route's 3 days
|
|
@@ -20,6 +20,9 @@
|
|
|
20
20
|
* npm-gate: <command> # #433 — the pack-allowlist gate, run before every npm publish
|
|
21
21
|
* version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable?
|
|
22
22
|
* final-grant: 123 # #441 — an operator's recorded decision letting deploy-tag's final be automatic
|
|
23
|
+
* health-url: https://… # #446 — deploy-tag-fast only: the public endpoint reporting the running version
|
|
24
|
+
* rollback: auto # #446 — deploy-tag-fast only: the deploy rolls itself back when that check fails
|
|
25
|
+
* final-spacing: 1h # #446 — deploy-tag-fast only: minimum time between finals (<N>h | <N>d, ≥ 1h)
|
|
23
26
|
*
|
|
24
27
|
* Two layers. The descriptor's ROW (exposure + deploy + production) is a fact about the repo; the
|
|
25
28
|
* ROUTE is how releases run on it. A row permits a fixed set of routes (ROW_ROUTES) and derives one
|
|
@@ -44,7 +47,7 @@
|
|
|
44
47
|
|
|
45
48
|
const axisAuthority = require('./axis-authority.js');
|
|
46
49
|
|
|
47
|
-
const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant']);
|
|
50
|
+
const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant', 'health-url', 'rollback', 'final-spacing']);
|
|
48
51
|
// #438: where the version a tag names comes from. `manifest` (the default) — every declared manifest
|
|
49
52
|
// (VERSION, package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it
|
|
50
53
|
// on trunk first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check
|
|
@@ -56,6 +59,18 @@ const VERSION_SOURCES = Object.freeze(['manifest', 'tag']);
|
|
|
56
59
|
// sit on — `deploy: tag` only. `deploy: manual` stays human: a person runs that deploy anyway.
|
|
57
60
|
const GRANTABLE_ROUTE = 'deploy-tag';
|
|
58
61
|
const GRANTABLE_ROW = 'released-tag';
|
|
62
|
+
// #446: the route that cuts a FINAL on every green trunk head — no candidate, no test period — and
|
|
63
|
+
// deploys it in the same run. It exists only on deploy: tag, only with the operator's recorded grant
|
|
64
|
+
// (the #441 reader, unchanged), and only where the repo declares a health-gated deploy that rolls
|
|
65
|
+
// itself back: those two declarations stand in for the test period it does not have. Its own keys —
|
|
66
|
+
// `health-url`, `rollback`, `final-spacing` — fit this route alone.
|
|
67
|
+
const FAST_ROUTE = 'deploy-tag-fast';
|
|
68
|
+
const GRANTABLE_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
|
|
69
|
+
const FAST_KEYS = Object.freeze(['health-url', 'rollback', 'final-spacing']);
|
|
70
|
+
const ROLLBACK = Object.freeze(['auto']);
|
|
71
|
+
// The minimum spacing between two finals on deploy-tag-fast: both the default and the floor. A burst
|
|
72
|
+
// of merges then deploys at most once an hour; a repo may lengthen it, never shorten it.
|
|
73
|
+
const FINAL_SPACING_HOURS = 1;
|
|
59
74
|
// #433: the npm opt-in. `npm` names the package directory release-auto.yml publishes (`.` for the
|
|
60
75
|
// root); `npm-gate` the command that proves the tarball holds only what was meant to ship. They are
|
|
61
76
|
// a pair — a publish with no gate is the stray-local-file leak the gate exists to stop — and they
|
|
@@ -84,7 +99,8 @@ const TEST_PERIOD_DAYS = 3;
|
|
|
84
99
|
* finalize how a final is reached: 'none' (no tags), 'after-test-period' (each clean
|
|
85
100
|
* candidate on its own clock), 'newest-clean' (the newest candidate clean for
|
|
86
101
|
* the period; a newer candidate does not restart an older one's clock),
|
|
87
|
-
* 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click'
|
|
102
|
+
* 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click',
|
|
103
|
+
* 'on-green-head' (#446: `release cut --auto` tags the final itself; no candidate).
|
|
88
104
|
*/
|
|
89
105
|
const ROUTE_POLICY = Object.freeze({
|
|
90
106
|
'none': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'nothing consumes a tag here, so no tags are cut' }),
|
|
@@ -92,6 +108,7 @@ const ROUTE_POLICY = Object.freeze({
|
|
|
92
108
|
'public-tool': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'auto', finalize: 'after-test-period', why: 'adopters install it and nothing deploys: every green trunk head gets a candidate, and the final tag is automatic after a clean test period' }),
|
|
93
109
|
'library-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-tag', why: 'a library released per merge and pinned by its consumers: no candidates, the tag triggers the publish and the route\'s checks still apply' }),
|
|
94
110
|
'deploy-tag': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'human-click', why: 'the tag deploys production, so the final tag is a human act' }),
|
|
111
|
+
'deploy-tag-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-green-head', why: 'the operator granted a final on every green trunk head, deployed in the same run behind a health-gated deploy that rolls itself back' }),
|
|
95
112
|
'live': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'the promotion is the deploy and stays human; no automatic tags' }),
|
|
96
113
|
});
|
|
97
114
|
const ROUTES = Object.freeze(Object.keys(ROUTE_POLICY));
|
|
@@ -105,7 +122,7 @@ const ROW_ROUTES = Object.freeze({
|
|
|
105
122
|
'no-tags': Object.freeze(['none']),
|
|
106
123
|
'live': Object.freeze(['live', 'none']),
|
|
107
124
|
'released-no-production': Object.freeze(['public-tool', 'rapid-app', 'library-fast', 'none']),
|
|
108
|
-
'released-tag': Object.freeze(['deploy-tag', 'none']),
|
|
125
|
+
'released-tag': Object.freeze(['deploy-tag', 'deploy-tag-fast', 'none']),
|
|
109
126
|
'released-manual': Object.freeze(['deploy-tag', 'none']),
|
|
110
127
|
'unmatched': Object.freeze(['none']),
|
|
111
128
|
});
|
|
@@ -151,7 +168,35 @@ function deriveDefault(cfg) {
|
|
|
151
168
|
/** A route's policy as an effective-shaped object (no `why`). */
|
|
152
169
|
function routePolicy(route) {
|
|
153
170
|
const p = ROUTE_POLICY[route];
|
|
154
|
-
return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null } : null;
|
|
171
|
+
return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null } : null;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** `6h` -> 6, `2d` -> 48; anything else (including `30m`, `0h`) -> null. */
|
|
175
|
+
function parseSpacing(v) {
|
|
176
|
+
const m = typeof v === 'string' ? /^([0-9]+)([hd])$/.exec(v.trim()) : null;
|
|
177
|
+
if (!m) return null;
|
|
178
|
+
const n = parseInt(m[1], 10) * (m[2] === 'd' ? 24 : 1);
|
|
179
|
+
return n > 0 ? n : null;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** A health URL is an absolute https:// URL with a host. */
|
|
183
|
+
function validHealthUrl(v) {
|
|
184
|
+
if (typeof v !== 'string' || !/^https:\/\/[^\s/]+/.test(v.trim())) return false;
|
|
185
|
+
try { return new URL(v.trim()).protocol === 'https:'; } catch { return false; }
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* #446: what a declared `deploy-tag-fast` still lacks — the operator's grant, the health URL, the
|
|
190
|
+
* rollback declaration. Empty array = all three present (shape only; the grant's tracker state is
|
|
191
|
+
* finalGrantVerdict's).
|
|
192
|
+
*/
|
|
193
|
+
function fastRoutePrerequisites(raw) {
|
|
194
|
+
const r = raw || {};
|
|
195
|
+
const missing = [];
|
|
196
|
+
if (parseGrantIssue(r['final-grant']) === null) missing.push("release.final-grant: <N> — the operator's recorded decision (colab decision <N> --record --ruled-by <human>)");
|
|
197
|
+
if (!validHealthUrl(r['health-url'])) missing.push('release.health-url: https://… — the public endpoint that reports the running version');
|
|
198
|
+
if (!ROLLBACK.includes(r.rollback)) missing.push('release.rollback: auto — the deploy rolls itself back when the health check fails');
|
|
199
|
+
return missing;
|
|
155
200
|
}
|
|
156
201
|
|
|
157
202
|
function parseTestPeriod(v) {
|
|
@@ -176,7 +221,7 @@ function evaluateRelease(cfg) {
|
|
|
176
221
|
const fromDerived = () => ({
|
|
177
222
|
route: derived.route, candidates: derived.candidates, candidatesPerDay: derived.candidatesPerDay,
|
|
178
223
|
testPeriodDays: derived.testPeriodDays, final: derived.final, finalize: derived.finalize, npm: null,
|
|
179
|
-
versionSource: 'manifest', finalGrant: null,
|
|
224
|
+
versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null,
|
|
180
225
|
});
|
|
181
226
|
let effective = fromDerived();
|
|
182
227
|
const findings = [];
|
|
@@ -222,6 +267,11 @@ function evaluateRelease(cfg) {
|
|
|
222
267
|
else if (!allowed.includes(v)) {
|
|
223
268
|
fail(`release.route: ${v} does not fit ${derived.axis} — that descriptor permits ${allowed.join(' or ')} (${routes}). ` +
|
|
224
269
|
'A route is chosen among the ones exposure + deploy permit; change those first if the repo really changed');
|
|
270
|
+
} else if (v === FAST_ROUTE && fastRoutePrerequisites(raw).length) {
|
|
271
|
+
// Fail closed: without its grant and its health gate the fast route would be an automatic,
|
|
272
|
+
// untested deploy nobody chose. The derived route (deploy-tag, human final) stays in effect.
|
|
273
|
+
fail(`release.route: ${FAST_ROUTE} needs the operator's grant and a declared health-gated deploy before it may stand — missing: ` +
|
|
274
|
+
`${fastRoutePrerequisites(raw).join('; ')} (${routes}). Until then the final stays a human act on route ${derived.route}`);
|
|
225
275
|
} else {
|
|
226
276
|
effective = routePolicy(v);
|
|
227
277
|
why = ROUTE_POLICY[v].why;
|
|
@@ -259,8 +309,14 @@ function evaluateRelease(cfg) {
|
|
|
259
309
|
if ('final-grant' in raw) {
|
|
260
310
|
const n = parseGrantIssue(raw['final-grant']);
|
|
261
311
|
if (n === null) fail(`release.final-grant is ${JSON.stringify(raw['final-grant'])}, expected the number of the decision issue that records the operator's ruling (e.g. 123 or "#123")`);
|
|
262
|
-
else if (effective.route
|
|
263
|
-
|
|
312
|
+
else if (effective.route === FAST_ROUTE) {
|
|
313
|
+
// #446: the route itself is the automatic final, so the grant takes effect from this line alone.
|
|
314
|
+
grant = { issue: n };
|
|
315
|
+
effective.finalGrant = grant;
|
|
316
|
+
} else if (raw.route === FAST_ROUTE) {
|
|
317
|
+
// The route was refused above; its grant line is not a second finding.
|
|
318
|
+
} else if (effective.route !== GRANTABLE_ROUTE || derived.row !== GRANTABLE_ROW) {
|
|
319
|
+
fail(`release.final-grant fits only route ${GRANTABLE_ROUTE} on deploy: tag (or ${FAST_ROUTE}) — ${route} on ${derived.axis} is not that (${routes}). ` +
|
|
264
320
|
(derived.row === 'released-manual' ? 'On deploy: manual a person runs the deploy anyway, so its final stays human' : 'Its final is not a deploying human act, so there is nothing to grant'));
|
|
265
321
|
} else grant = { issue: n };
|
|
266
322
|
}
|
|
@@ -268,7 +324,9 @@ function evaluateRelease(cfg) {
|
|
|
268
324
|
if ('final' in raw) {
|
|
269
325
|
const v = raw.final;
|
|
270
326
|
if (!FINAL.includes(v)) fail(`release.final is ${JSON.stringify(v)}, expected "auto" or "human"`);
|
|
271
|
-
else if (
|
|
327
|
+
else if (effective.route === FAST_ROUTE) {
|
|
328
|
+
if (v === 'human') fail(`release.final: human on route ${FAST_ROUTE} — that route has no candidate for a human to finalize; use route deploy-tag for a human final`);
|
|
329
|
+
} else if (v === 'auto' && effective.final === 'human' && grant) {
|
|
272
330
|
// #441: an automatic final that deploys production — permitted only by the recorded grant.
|
|
273
331
|
effective.final = 'auto';
|
|
274
332
|
effective.finalize = 'after-test-period';
|
|
@@ -288,7 +346,7 @@ function evaluateRelease(cfg) {
|
|
|
288
346
|
const v = raw['test-period'];
|
|
289
347
|
const days = parseTestPeriod(v);
|
|
290
348
|
if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
|
|
291
|
-
else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route}
|
|
349
|
+
else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
|
|
292
350
|
else if (days < effective.testPeriodDays) {
|
|
293
351
|
widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer`);
|
|
294
352
|
} else effective.testPeriodDays = days;
|
|
@@ -301,6 +359,21 @@ function evaluateRelease(cfg) {
|
|
|
301
359
|
else effective.versionSource = v;
|
|
302
360
|
}
|
|
303
361
|
|
|
362
|
+
// #446: the fast route's own keys — only there, and the floor on spacing.
|
|
363
|
+
const fastKeys = FAST_KEYS.filter((k) => k in raw);
|
|
364
|
+
if (effective.route === FAST_ROUTE) {
|
|
365
|
+
effective.healthGate = { url: raw['health-url'].trim(), rollback: raw.rollback };
|
|
366
|
+
effective.finalSpacingHours = FINAL_SPACING_HOURS;
|
|
367
|
+
if ('final-spacing' in raw) {
|
|
368
|
+
const h = parseSpacing(raw['final-spacing']);
|
|
369
|
+
if (h === null) fail(`release.final-spacing is ${JSON.stringify(raw['final-spacing'])}, expected hours or days like "${FINAL_SPACING_HOURS}h" or "1d"`);
|
|
370
|
+
else if (h < FINAL_SPACING_HOURS) widen('final-spacing', raw['final-spacing'], `finals are at least ${FINAL_SPACING_HOURS}h apart. Set ${FINAL_SPACING_HOURS}h or longer`);
|
|
371
|
+
else effective.finalSpacingHours = h;
|
|
372
|
+
}
|
|
373
|
+
} else if (fastKeys.length && raw.route !== FAST_ROUTE) {
|
|
374
|
+
fail(`release.${fastKeys.join(' / release.')} fits only route ${FAST_ROUTE} — ${route} on ${derived.axis} is not that (${routes}). Remove the key${fastKeys.length > 1 ? 's' : ''}`);
|
|
375
|
+
}
|
|
376
|
+
|
|
304
377
|
// 3. npm (#433) — only on a route where a tag publishes to adopters and deploys nothing.
|
|
305
378
|
effective.npm = null;
|
|
306
379
|
if ('npm' in raw || 'npm-gate' in raw) {
|
|
@@ -352,7 +425,8 @@ function finalGrantVerdict(record, { issue, trust } = {}) {
|
|
|
352
425
|
}
|
|
353
426
|
|
|
354
427
|
module.exports = {
|
|
355
|
-
VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW,
|
|
428
|
+
VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, ROLLBACK, FINAL_SPACING_HOURS,
|
|
429
|
+
parseGrantIssue, finalGrantVerdict, parseSpacing, validHealthUrl, fastRoutePrerequisites,
|
|
356
430
|
KEYS, INPUT_KEYS, NPM_KEYS, NPM_ROUTES, CANDIDATES, FINAL, TEST_PERIOD_DAYS, ROUTES, ROUTE_POLICY, ROW_ROUTES,
|
|
357
431
|
deriveDefault, evaluateRelease, parseTestPeriod, routePolicy,
|
|
358
432
|
};
|