@futurelastic/colab-handbook 1.18.0-rc.4 → 1.18.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/release-auto.yml +3 -3
- package/tools/colab +21 -10
- package/tools/lib/release-cut.js +32 -7
- package/tools/lib/release-finalize.js +17 -4
package/package.json
CHANGED
|
@@ -516,7 +516,7 @@ jobs:
|
|
|
516
516
|
{
|
|
517
517
|
echo "### colab promote --auto"
|
|
518
518
|
echo
|
|
519
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
519
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
520
520
|
echo
|
|
521
521
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
522
522
|
if [ "${DRY_RUN:-false}" = "true" ]; then
|
|
@@ -585,7 +585,7 @@ jobs:
|
|
|
585
585
|
{
|
|
586
586
|
echo "### colab release cut --auto"
|
|
587
587
|
echo
|
|
588
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
588
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
589
589
|
echo
|
|
590
590
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
591
591
|
if [ "${DRY_RUN:-false}" = "true" ]; then
|
|
@@ -721,7 +721,7 @@ jobs:
|
|
|
721
721
|
{
|
|
722
722
|
echo "### colab release finalize --auto — $STATE"
|
|
723
723
|
echo
|
|
724
|
-
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
724
|
+
jq -r '.checks[]? | "- \(if .checked == false then "·" elif .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
725
725
|
echo
|
|
726
726
|
if [ -n "$WHY" ]; then echo "**Why no final:** $WHY"; echo; fi
|
|
727
727
|
if [ "$(jq -r '(.skipped // []) | length' "$OUT")" != "0" ]; then
|
package/tools/colab
CHANGED
|
@@ -1311,7 +1311,9 @@ Refuses, naming each failed condition (all are reported, not just the first):
|
|
|
1311
1311
|
under a project.yml \`migrations:\` prefix) or an existing migration was
|
|
1312
1312
|
edited/deleted. Other layouts are not read — a declared migration in another
|
|
1313
1313
|
format is NAMED in the detail, and the release notes still owe the §6
|
|
1314
|
-
judgement on the diff
|
|
1314
|
+
judgement on the diff. When nothing was read — no default layout and no
|
|
1315
|
+
\`migrations:\` declared, or a declared migration in another format changed —
|
|
1316
|
+
the row prints · "not checked" (#670): it refuses nothing, and it is never a ✓
|
|
1315
1317
|
switch-dependencies a colab:switch marker is malformed, or a finished switch needs one that is not
|
|
1316
1318
|
manifest-version the tag does not equal the version a manifest declares (VERSION, package.json,
|
|
1317
1319
|
Cargo.toml [package], else [workspace.package] (#620), pyproject.toml
|
|
@@ -1470,13 +1472,22 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
|
|
|
1470
1472
|
// same one rule the ship gate reads (tools/lib/migration-paths.js), never a second regex.
|
|
1471
1473
|
const declared = migrationPaths.unionPaths(projectDoc(repoAbs), projectDocAt(repoAbs, sha));
|
|
1472
1474
|
const changes = releaseCutChanges(repoAbs, lastFinal, sha, declared);
|
|
1475
|
+
// #670: does a default layout exist at the candidate — anywhere in the tree, as the defaults are
|
|
1476
|
+
// matched (migration-paths.js isMigrationPath)? Without one and with nothing declared, the check
|
|
1477
|
+
// read nothing: "not checked", never a ✓. null = the tree could not be read, never "absent".
|
|
1478
|
+
const layoutR = git.git(['ls-tree', '-r', '-d', '--name-only', sha], repoAbs);
|
|
1479
|
+
const layout = layoutR.ok ? layoutR.stdout.split('\n').some((d) => d && migrationPaths.isMigrationPath(`${d}/`, [])) : null;
|
|
1473
1480
|
const schema = changes === null
|
|
1474
1481
|
? { ok: false, unread: true, detail: 'git diff failed — schema changes cannot be read' }
|
|
1475
|
-
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared);
|
|
1482
|
+
: releaseCut.schemaVerdict(changes, lastFinal || 'the first commit', declared, layout);
|
|
1476
1483
|
// #441: every migration file since the last final, destructive or not — an operator-granted
|
|
1477
1484
|
// automatic final refuses an ungranted one (release-finalize.js migrationGrantVerdict).
|
|
1478
1485
|
const migrations = changes === null ? null : changes.filter((c) => releaseCut.isMigrationPath(c.path, declared)).map((c) => c.path);
|
|
1479
|
-
|
|
1486
|
+
// #671: could a migration have been seen at all? A declared prefix is a layout; otherwise the
|
|
1487
|
+
// default-layout reading above (null = unread, never "absent"). The grant gate fails closed
|
|
1488
|
+
// without one, so its empty list never reads "nothing read" as "nothing changed".
|
|
1489
|
+
const migrationLayout = declared.length ? true : layout;
|
|
1490
|
+
return { ci, suite, schema, switches, issues, migrations, migrationLayout };
|
|
1480
1491
|
}
|
|
1481
1492
|
|
|
1482
1493
|
/**
|
|
@@ -1614,7 +1625,7 @@ function finalTags(repoAbs, onlyTags = null) {
|
|
|
1614
1625
|
* since the newest final. The version is computed here only to find that tracking issue; decide()
|
|
1615
1626
|
* computes it again from the same inputs, so the two cannot disagree.
|
|
1616
1627
|
*/
|
|
1617
|
-
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, remoteTags = null }) {
|
|
1628
|
+
function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths, migrationLayout = null, remoteTags = null }) {
|
|
1618
1629
|
const grantDecl = policy.effective.finalGrant;
|
|
1619
1630
|
const trust = trustAt(repoAbs, `${remote}/main`);
|
|
1620
1631
|
const finalGrant = isGhUsable(repoAbs)
|
|
@@ -1634,7 +1645,7 @@ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, au
|
|
|
1634
1645
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
1635
1646
|
if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
|
|
1636
1647
|
}
|
|
1637
|
-
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
|
|
1648
|
+
const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal, layout: migrationLayout }), paths: paths || null };
|
|
1638
1649
|
const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs, remoteTags), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
|
|
1639
1650
|
return { finalGrant, holds, migrations, spacing, tracking };
|
|
1640
1651
|
}
|
|
@@ -1727,7 +1738,7 @@ function cmdReleaseCut(argv) {
|
|
|
1727
1738
|
const tags = lines(git.git(['tag', '--list'], repoAbs)).filter(onRemote);
|
|
1728
1739
|
const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs)).filter(onRemote);
|
|
1729
1740
|
|
|
1730
|
-
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
|
|
1741
|
+
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince, migrationLayout } = measureCandidateConditions(repoAbs, {
|
|
1731
1742
|
sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
|
|
1732
1743
|
verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
|
|
1733
1744
|
});
|
|
@@ -1743,7 +1754,7 @@ function cmdReleaseCut(argv) {
|
|
|
1743
1754
|
// #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
|
|
1744
1755
|
// measured only there, so every candidate route's run is what it was.
|
|
1745
1756
|
const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
|
|
1746
|
-
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, remoteTags }) : {};
|
|
1757
|
+
const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince, migrationLayout, remoteTags }) : {};
|
|
1747
1758
|
if (fast && auto) auto.spacing = fastFacts.spacing;
|
|
1748
1759
|
// #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
|
|
1749
1760
|
// read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
|
|
@@ -1862,7 +1873,7 @@ function cmdReleaseCut(argv) {
|
|
|
1862
1873
|
for (const l of verdict.signals.lines) print(` · ${l}`);
|
|
1863
1874
|
}
|
|
1864
1875
|
const width = Math.max(...verdict.checks.map((c) => c.condition.length));
|
|
1865
|
-
for (const c of verdict.checks) print(` ${c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
|
|
1876
|
+
for (const c of verdict.checks) print(` ${c.checked === false ? '·' : c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
|
|
1866
1877
|
print('');
|
|
1867
1878
|
if (verdict.noop) {
|
|
1868
1879
|
print(fast
|
|
@@ -2230,7 +2241,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2230
2241
|
const mg = tracking && tracking.number
|
|
2231
2242
|
? migrationGrant.evaluateIssue(rec, cand.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
|
|
2232
2243
|
: { ok: false, reason: 'no tracking issue yet to carry a grant' };
|
|
2233
|
-
migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }) });
|
|
2244
|
+
migrations = releaseFinalize.migrationGrantVerdict({ paths: conditions.migrations, grant: mg, since: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha, onlyTags: remoteTags }), layout: conditions.migrationLayout });
|
|
2234
2245
|
}
|
|
2235
2246
|
const verdict = releaseFinalize.decide({
|
|
2236
2247
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
|
@@ -2379,7 +2390,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2379
2390
|
} else {
|
|
2380
2391
|
print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
|
|
2381
2392
|
const width = Math.max(...verdict.checks.map((c) => c.condition.length));
|
|
2382
|
-
for (const c of verdict.checks) print(` ${c.ok ? '✓' : (c.required ? '✗' : '·')} ${c.condition.padEnd(width)} ${c.detail}`);
|
|
2393
|
+
for (const c of verdict.checks) print(` ${c.checked === false ? '·' : c.ok ? '✓' : (c.required ? '✗' : '·')} ${c.condition.padEnd(width)} ${c.detail}`);
|
|
2383
2394
|
if (walk && skipped.length) {
|
|
2384
2395
|
print(' other open candidates:');
|
|
2385
2396
|
for (const x of skipped) print(` · ${x.tag}: ${x.state}${x.detail ? ` — ${x.detail}` : ''}`);
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -854,8 +854,21 @@ function laravelUpBody(text) {
|
|
|
854
854
|
* — an edited or deleted migration counts as destructive, because rewriting history a database has
|
|
855
855
|
* already run is not an add. A false positive costs a human cutting the candidate; a false negative
|
|
856
856
|
* is the §6 judgement the release notes still owe (read the diff, not only this).
|
|
857
|
+
*
|
|
858
|
+
* #670: a third outcome beside ✓ and ✗ — NOT CHECKED, `{ ok: true, checked: false }`. It refuses
|
|
859
|
+
* nothing (an absent `migrations:` still changes no gate — project.schema.md `migrations`; for a
|
|
860
|
+
* DECLARED migration in an unread format, the #441 migration-grant check still holds an automatic
|
|
861
|
+
* final), but it is never printed as a green pass:
|
|
862
|
+
* a ✓ reading "other layouts are not read" was read as "no migration" by the human finalizing a
|
|
863
|
+
* release whose migrations sat in a directory this check never looked at. Two cases:
|
|
864
|
+
* - nothing declared and no default layout at the candidate (`layout` false) — nothing was read;
|
|
865
|
+
* - a declared migration in a format the heuristic does not read changed, and nothing it did read
|
|
866
|
+
* is destructive (a destructive read file is still ✗).
|
|
867
|
+
* `layout` = does `database/migrations/` or `prisma/migrations/` exist in the tree at the candidate:
|
|
868
|
+
* true / false / null (the tree could not be read — never "absent"). Undefined = a caller that does
|
|
869
|
+
* not measure it, read as today: present.
|
|
857
870
|
*/
|
|
858
|
-
function schemaVerdict(changes, since, declared) {
|
|
871
|
+
function schemaVerdict(changes, since, declared, layout) {
|
|
859
872
|
const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
|
|
860
873
|
const migrations = inPaths.filter((c) => /\.(php|sql)$/.test(c.path));
|
|
861
874
|
// #383: a declared path widens what COUNTS as a migration, not what this heuristic can READ. A
|
|
@@ -867,10 +880,16 @@ function schemaVerdict(changes, since, declared) {
|
|
|
867
880
|
? inPaths.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
|
|
868
881
|
: [];
|
|
869
882
|
const scope = `Laravel database/migrations + Prisma prisma/migrations${declared && declared.length ? ` + declared ${declared.join(', ')} (php/sql only)` : ''} — other layouts are not read`;
|
|
870
|
-
const
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
883
|
+
const hasDeclared = !!(declared && declared.length);
|
|
884
|
+
const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
|
|
885
|
+
const unreadWhy = () => `${unread.length} declared migration file(s) changed since ${since} in a format this check does not read (php/sql only) — a human reads them before the final: ${unread.map((c) => c.path).join(', ')}`;
|
|
886
|
+
const howToDeclare = 'a repo whose migrations live elsewhere declares their directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); a repo with no database has nothing to declare';
|
|
887
|
+
if (!migrations.length) {
|
|
888
|
+
if (unread.length) return notChecked(unreadWhy());
|
|
889
|
+
if (!hasDeclared && layout === false) return notChecked(`no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate and no \`migrations:\` declared, so no migration was read — ${howToDeclare}`);
|
|
890
|
+
if (!hasDeclared && layout === null) return notChecked(`the tree at the candidate could not be read for a migration layout, so no migration was read — ${howToDeclare}`);
|
|
891
|
+
return { ok: true, detail: `no migration file changed since ${since} (${scope})` };
|
|
892
|
+
}
|
|
874
893
|
const findings = [];
|
|
875
894
|
for (const c of migrations) {
|
|
876
895
|
const st = String(c.status || '').charAt(0);
|
|
@@ -888,7 +907,8 @@ function schemaVerdict(changes, since, declared) {
|
|
|
888
907
|
if (findings.length) {
|
|
889
908
|
return { ok: false, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
|
|
890
909
|
}
|
|
891
|
-
|
|
910
|
+
if (unread.length) return notChecked(`${migrations.length} migration file(s) added since ${since}, none destructive — but ${unreadWhy()}`);
|
|
911
|
+
return { ok: true, detail: `${migrations.length} migration file(s) added since ${since}, none destructive (${scope})` };
|
|
892
912
|
}
|
|
893
913
|
|
|
894
914
|
// ---- §6 condition 4: switch dependencies -------------------------------------------------------
|
|
@@ -1165,7 +1185,12 @@ function decide(facts) {
|
|
|
1165
1185
|
|
|
1166
1186
|
for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
1167
1187
|
if (!verdict) add(condition, false, 'not measured', true);
|
|
1168
|
-
else
|
|
1188
|
+
else {
|
|
1189
|
+
add(condition, verdict.ok, verdict.detail, isUnread(verdict));
|
|
1190
|
+
// #670: a not-checked verdict passes but is not a ✓ — the one optional field a row can carry,
|
|
1191
|
+
// present only then, so every other row (and `--json` on every other run) is unchanged.
|
|
1192
|
+
if (verdict.checked === false) checks[checks.length - 1].checked = false;
|
|
1193
|
+
}
|
|
1169
1194
|
}
|
|
1170
1195
|
|
|
1171
1196
|
// #610: a final needs the heavy lane green at its exact sha, under every integration profile. Only
|
|
@@ -560,11 +560,23 @@ function regressionVerdict(edges, { periodStart }) {
|
|
|
560
560
|
* human gate. `paths` is every migration file changed since the last final (null = unread);
|
|
561
561
|
* `grant` is migration-grant.js evaluateIssue() of the version's TRACKING issue, bound to the
|
|
562
562
|
* version (`colab migration-grant <tracking> --branch vX.Y.Z`), or null when there was nothing to
|
|
563
|
-
* evaluate.
|
|
563
|
+
* evaluate. `layout` (#671) says whether a migration could have been seen at the candidate at all:
|
|
564
|
+
* true = a `migrations:` prefix is declared or a default layout (Laravel database/migrations/,
|
|
565
|
+
* Prisma prisma/migrations/) exists in the tree; false = neither, so an empty `paths` is "nothing
|
|
566
|
+
* read", not "nothing changed"; null/absent = the tree could not be read. An empty `paths` passes
|
|
567
|
+
* only with a layout. Returns { ok, detail } (+ unread: true when something could not be read).
|
|
564
568
|
*/
|
|
565
|
-
function migrationGrantVerdict({ paths, grant, since }) {
|
|
569
|
+
function migrationGrantVerdict({ paths, grant, since, layout }) {
|
|
566
570
|
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' };
|
|
567
|
-
if (!paths.length)
|
|
571
|
+
if (!paths.length) {
|
|
572
|
+
// #671: fail closed where nothing could have been seen — an automatically deployed final never
|
|
573
|
+
// reads "nothing read" as "nothing changed". The way out is named in the detail, never implied —
|
|
574
|
+
// route-neutral: release finalize prints its own human command, and route deploy-tag-fast has none.
|
|
575
|
+
const wayOut = 'declare the migration directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); until then the final is a human act, not the grant\'s — and a repo with no database has no layout to declare, so its final stays one';
|
|
576
|
+
if (layout === false) return { ok: false, detail: `no migration was read since ${since || 'the first commit'}: no \`migrations:\` declared and no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate, so a migration elsewhere would be invisible — ${wayOut}` };
|
|
577
|
+
if (layout !== true) return { ok: false, unread: true, detail: `the tree at the candidate could not be read for a migration layout, so an empty migration list since ${since || 'the first commit'} is not evidence that none changed — ${wayOut}` };
|
|
578
|
+
return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|
|
579
|
+
}
|
|
568
580
|
const list = paths.join(', ');
|
|
569
581
|
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}` };
|
|
570
582
|
return {
|
|
@@ -713,6 +725,7 @@ function decide(facts) {
|
|
|
713
725
|
if (hv) add('heavy-lane', hv.ok, hv.detail);
|
|
714
726
|
for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
715
727
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
728
|
+
if (v && v.checked === false) checks[checks.length - 1].checked = false; // #670: passes, never a ✓
|
|
716
729
|
}
|
|
717
730
|
// #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
|
|
718
731
|
for (const c of releaseTag.preTagChecks({ tag: cand.version, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: 'main', versionSource: p.effective.versionSource === 'tag' ? 'tag' : 'manifest' })) add(c.condition, c.ok, c.detail);
|
|
@@ -802,7 +815,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
|
|
|
802
815
|
verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
|
|
803
816
|
'',
|
|
804
817
|
'Conditions (CONVENTIONS.md §6):',
|
|
805
|
-
...verdict.checks.map((c) => `- ${c.condition}: ${c.ok ? 'ok' : (c.required ? 'FAILED' : 'informational')} — ${c.detail}`),
|
|
818
|
+
...verdict.checks.map((c) => `- ${c.condition}: ${c.checked === false ? 'not checked' : c.ok ? 'ok' : (c.required ? 'FAILED' : 'informational')} — ${c.detail}`),
|
|
806
819
|
].filter((l) => l !== null).join('\n') + '\n';
|
|
807
820
|
}
|
|
808
821
|
|