@futurelastic/colab-handbook 1.14.1-rc.9 → 1.15.0-rc.2
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/README.md +1 -1
- package/templates/release-auto.yml +29 -2
- package/tools/colab +54 -15
- package/tools/lib/release-cut.js +70 -3
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -79,7 +79,7 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
|
|
|
79
79
|
| `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
|
|
80
80
|
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
|
|
81
81
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
82
|
-
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
82
|
+
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
83
83
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
84
84
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
85
85
|
| `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
|
|
@@ -15,7 +15,9 @@
|
|
|
15
15
|
# everywhere else)
|
|
16
16
|
# your CI workflow finished green on main colab release cut --auto → vX.Y.Z-rc.N
|
|
17
17
|
# (on `trunk: dev`: the promotion's push), (#443: the newest candidate always names main's
|
|
18
|
-
# and the daily schedule head; a head already carrying one is a no-op
|
|
18
|
+
# and the daily schedule head; a head already carrying one is a no-op.
|
|
19
|
+
# #622: a CI-fired run cuts the sha that run
|
|
20
|
+
# tested — `--sha` — even once main moved on)
|
|
19
21
|
# a daily schedule colab release finalize --auto → vX.Y.Z (or a
|
|
20
22
|
# hand-off where
|
|
21
23
|
# the final is a
|
|
@@ -457,16 +459,41 @@ jobs:
|
|
|
457
459
|
# declared release.candidates-per-day window held back is tagged once the window ends, even
|
|
458
460
|
# with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
|
|
459
461
|
# right after this run promoted: that head has no CI yet — the dispatched run cuts it.
|
|
462
|
+
# #622: a run fired by workflow_run cuts the sha THAT CI run tested (`--sha`), not main's head —
|
|
463
|
+
# on a busy trunk something lands during almost every suite run, so the green sha is rarely
|
|
464
|
+
# still the head when its run ends, and the head itself has no green run yet. The head gets its
|
|
465
|
+
# own candidate when its own run is green; a run that finishes out of order (a later commit
|
|
466
|
+
# already carries a candidate) is a no-op, so `next` never moves backwards. The schedule and a
|
|
467
|
+
# dispatch still cut main's head. While the cut reads an older sha the checkout is detached there
|
|
468
|
+
# (a release.guard-run reads the working tree) and restored afterwards.
|
|
460
469
|
- name: Cut a candidate (colab release cut --auto)
|
|
461
470
|
id: cut
|
|
462
471
|
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
|
|
472
|
+
env:
|
|
473
|
+
EVENT: ${{ github.event_name }}
|
|
474
|
+
RUN_SHA: ${{ github.event.workflow_run.head_sha }}
|
|
463
475
|
run: |
|
|
464
476
|
set -uo pipefail
|
|
465
477
|
eval "$RETRY_TRANSIENT"
|
|
466
478
|
OUT="$RUNNER_TEMP/cut.json"
|
|
467
479
|
rc=0
|
|
468
480
|
DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
|
|
469
|
-
|
|
481
|
+
AT=(); RESTORE=""
|
|
482
|
+
if [ "${EVENT:-}" = "workflow_run" ] && [ -n "${RUN_SHA:-}" ]; then
|
|
483
|
+
if git rev-parse --git-dir > /dev/null 2>&1 && [ "$(git rev-parse HEAD)" != "$RUN_SHA" ]; then
|
|
484
|
+
RESTORE="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
|
|
485
|
+
git checkout --quiet --detach "$RUN_SHA" || RESTORE=""
|
|
486
|
+
fi
|
|
487
|
+
# Asked AFTER the detach, of the CLI that will run: a CLI older than #622 (a HANDBOOK_REF no
|
|
488
|
+
# final with --sha has reached yet, or a checkout's own CLI at an older sha) cuts the head.
|
|
489
|
+
if grep -q -- '--sha <sha>' <<< "$(node "$COLAB" release cut --help 2> /dev/null)"; then
|
|
490
|
+
AT=(--sha "$RUN_SHA")
|
|
491
|
+
elif [ -n "$RESTORE" ]; then
|
|
492
|
+
git checkout --quiet "$RESTORE"; RESTORE=""
|
|
493
|
+
fi
|
|
494
|
+
fi
|
|
495
|
+
retry_transient node "$COLAB" release cut --auto ${AT[@]+"${AT[@]}"} ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
|
|
496
|
+
[ -z "$RESTORE" ] || git checkout --quiet "$RESTORE"
|
|
470
497
|
# A verdict is JSON carrying `ok`; anything else is a run that never decided.
|
|
471
498
|
if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
|
|
472
499
|
echo "::error::colab release cut produced no verdict (exit $rc)"
|
package/tools/colab
CHANGED
|
@@ -1252,7 +1252,7 @@ function existingWorktreeFor(repoAbs, wtName, branch) {
|
|
|
1252
1252
|
}
|
|
1253
1253
|
|
|
1254
1254
|
const HELP_RELEASE = `colab release <issue> [--repo <path>]
|
|
1255
|
-
colab release cut [--repo <path>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
|
|
1255
|
+
colab release cut [--repo <path>] [--sha <sha>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
|
|
1256
1256
|
colab release finalize [--repo <path>] [--tag vX.Y.Z-rc.N] [--answered-by <name>] [--dry] [--json] (see: colab release finalize --help)
|
|
1257
1257
|
colab release npm [--repo <path>] [--json] (see: colab release npm --help)
|
|
1258
1258
|
|
|
@@ -1284,9 +1284,9 @@ said so. Worktree claims never held the checkout; \`colab worktree rm\` owns the
|
|
|
1284
1284
|
// release skill's (#339) and never this command's.
|
|
1285
1285
|
// ---------------------------------------------------------------------------
|
|
1286
1286
|
|
|
1287
|
-
const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
|
|
1287
|
+
const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--sha <sha>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
|
|
1288
1288
|
|
|
1289
|
-
Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head — only where CONVENTIONS.md §6's release
|
|
1289
|
+
Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head (or the commit --sha names) — only where CONVENTIONS.md §6's release
|
|
1290
1290
|
rung lets an agent, and only once every condition below holds on that exact commit. Creates an
|
|
1291
1291
|
annotated tag (the bump, its reason and every checked condition are recorded in its message) and
|
|
1292
1292
|
pushes it to origin. NEVER creates a final vX.Y.Z tag — finalizing is the release skill's.
|
|
@@ -1302,7 +1302,10 @@ Refuses, naming each failed condition (all are reported, not just the first):
|
|
|
1302
1302
|
already-candidate this commit already carries a candidate of the same version
|
|
1303
1303
|
ci-green every run at the commit finished and one succeeded — colab ship's whole-sha check
|
|
1304
1304
|
full-suite every workflow that ran at the commit has a successful run (a cancelled-only
|
|
1305
|
-
workflow never ran its tests)
|
|
1305
|
+
workflow never ran its tests). Both read only the runs that verify the code,
|
|
1306
|
+
by colab ship's rule: a schedule / workflow_dispatch / workflow_run run (a
|
|
1307
|
+
nightly still in flight) is set aside and named; project.yml
|
|
1308
|
+
ship-gate-workflows / ship-ignore-workflows narrow it the same way
|
|
1306
1309
|
schema-additive a migration since the last final tag is destructive (Laravel database/migrations
|
|
1307
1310
|
up() drops/renames/->change(), Prisma DROP/RENAME/ALTER COLUMN, and .php/.sql
|
|
1308
1311
|
under a project.yml \`migrations:\` prefix) or an existing migration was
|
|
@@ -1370,6 +1373,14 @@ The bump (without --auto) is release-status's semverSuggestion since the last fi
|
|
|
1370
1373
|
patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
|
|
1371
1374
|
--bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
|
|
1372
1375
|
--reason "<why>" why the override
|
|
1376
|
+
--sha <sha> (#622) cut at this commit instead of main's head — the qualified sha a busy trunk
|
|
1377
|
+
has already moved past. Every condition above is measured at it; on-trunk
|
|
1378
|
+
requires it on main. One more row when it is not the head:
|
|
1379
|
+
qualified-sha refused (a NO-OP under --auto) when a release tag already names a
|
|
1380
|
+
later commit (the newer candidate stands), on a final route (a
|
|
1381
|
+
final is tagged only on main's head), or --auto under a
|
|
1382
|
+
candidates-per-day cap (the cut is spent on the head)
|
|
1383
|
+
The release workflow passes the sha its triggering CI run tested.
|
|
1373
1384
|
--dry measure and report; create and push nothing
|
|
1374
1385
|
--json machine-readable: { ok, tag, created, checks: [{condition, ok, detail}], ... }
|
|
1375
1386
|
--repo <path> the repo (default: the one you are in)
|
|
@@ -1432,7 +1443,7 @@ function releaseCutChanges(repoAbs, from, sha, declared) {
|
|
|
1432
1443
|
* — by branch window for a fresh head (cut), by commit for an older candidate (finalize). Also
|
|
1433
1444
|
* returns the issue list it read (null when unread or gh unusable), so a caller does not read it twice.
|
|
1434
1445
|
*/
|
|
1435
|
-
function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues }) {
|
|
1446
|
+
function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues, verifying }) {
|
|
1436
1447
|
let ci; let suite; let switches; let issues = null;
|
|
1437
1448
|
if (!isGhUsable(repoAbs)) {
|
|
1438
1449
|
const why = ghUnusableWhy(repoAbs);
|
|
@@ -1441,11 +1452,16 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
|
|
|
1441
1452
|
switches = { ok: false, unread: true, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
|
|
1442
1453
|
} else {
|
|
1443
1454
|
// #616: a workflow whose every run at the sha was skipped did not run — not counted either way.
|
|
1444
|
-
|
|
1455
|
+
// #624: `verifying` (release cut only) narrows the rows to the runs that verify the code — a
|
|
1456
|
+
// scheduled run still in flight at the sha is not part of its verdict. Finalize passes none.
|
|
1457
|
+
const read = verifying ? releaseCut.verifyingRunsForCut(readRuns(), verifying) : { rows: readRuns() };
|
|
1458
|
+
const note = releaseCut.verifyingNote(read);
|
|
1459
|
+
const rows = releaseCut.withoutSkippedOnlyWorkflows(read.rows);
|
|
1445
1460
|
const run = git.summarizeRunsForCommit(rows, sha);
|
|
1446
1461
|
if (!run) ci = { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
|
|
1447
|
-
else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail }; }
|
|
1462
|
+
else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail + note }; }
|
|
1448
1463
|
suite = releaseCut.fullSuiteVerdict(rows, at);
|
|
1464
|
+
if (note && rows) suite = { ...suite, detail: suite.detail + note };
|
|
1449
1465
|
// #423: an --auto finalize judges several candidates in one run — the issue list is read once.
|
|
1450
1466
|
issues = knownIssues !== undefined ? knownIssues : readAllIssuesForSwitches(repoAbs);
|
|
1451
1467
|
switches = releaseCut.switchVerdict(issues);
|
|
@@ -1655,10 +1671,11 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
|
|
|
1655
1671
|
|
|
1656
1672
|
function cmdReleaseCut(argv) {
|
|
1657
1673
|
const opts = parseArgs(argv, {
|
|
1658
|
-
values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
|
|
1674
|
+
values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason', '--sha': 'sha' },
|
|
1659
1675
|
flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
|
|
1660
1676
|
});
|
|
1661
1677
|
if (opts.help) return print(HELP_RELEASE_CUT);
|
|
1678
|
+
if (opts.sha !== undefined && !/^[0-9a-f]{4,40}$/i.test(String(opts.sha))) throw new UserError(`--sha takes a commit sha (hex, 4–40 chars), got ${JSON.stringify(opts.sha)} — run \`git rev-parse <rev>\` and pass the sha it prints`);
|
|
1662
1679
|
if (opts._.length) throw new UserError(`release cut takes no positional arguments (got: ${opts._.join(' ')})`);
|
|
1663
1680
|
if (opts.auto && (opts.bump || opts.reason)) throw new UserError('--auto computes the bump with no human input — --bump/--reason cannot be combined with it');
|
|
1664
1681
|
if (opts.reason && !opts.bump) throw new UserError('--reason records why --bump overrode the computed bump — pass --bump with it');
|
|
@@ -1678,7 +1695,15 @@ function cmdReleaseCut(argv) {
|
|
|
1678
1695
|
const trunkFetch = offTrunk && opts.auto ? git.git(['fetch', remote, trunk], repoAbs) : null;
|
|
1679
1696
|
const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
|
|
1680
1697
|
if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — candidates are cut from main (CONVENTIONS.md §6: never from dev)`);
|
|
1681
|
-
const
|
|
1698
|
+
const head = shaR.stdout;
|
|
1699
|
+
// #622: --sha names the commit to cut — a qualified sha a busy trunk has already moved past. Every
|
|
1700
|
+
// condition below is measured at it; on-trunk still requires it to be an ancestor of main.
|
|
1701
|
+
let sha = head;
|
|
1702
|
+
if (opts.sha) {
|
|
1703
|
+
const r = git.git(['rev-parse', '--verify', '--quiet', `${opts.sha}^{commit}`], repoAbs);
|
|
1704
|
+
if (!r.ok || !r.stdout) throw new UserError(`--sha ${opts.sha} is not a commit in this clone (after fetching ${remote}/main) — run \`git log --oneline ${remote}/main\` and pass a sha from it`);
|
|
1705
|
+
sha = r.stdout;
|
|
1706
|
+
}
|
|
1682
1707
|
const at = `main@${shortSha(sha)}`;
|
|
1683
1708
|
|
|
1684
1709
|
const wf = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
|
|
@@ -1695,7 +1720,7 @@ function cmdReleaseCut(argv) {
|
|
|
1695
1720
|
const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
|
|
1696
1721
|
const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
|
|
1697
1722
|
const suggestion = lastFinal
|
|
1698
|
-
? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${
|
|
1723
|
+
? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${sha}`)) // #622: the bump reads what the tagged commit carries
|
|
1699
1724
|
: { bump: null, why: 'no final tag yet' };
|
|
1700
1725
|
const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
|
|
1701
1726
|
const onRemote = (t) => remoteTags.has(t);
|
|
@@ -1704,6 +1729,7 @@ function cmdReleaseCut(argv) {
|
|
|
1704
1729
|
|
|
1705
1730
|
const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
|
|
1706
1731
|
sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
|
|
1732
|
+
verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
|
|
1707
1733
|
});
|
|
1708
1734
|
const { manifests, ancestry } = measurePreTag(repoAbs, sha, `${remote}/main`); // #424
|
|
1709
1735
|
|
|
@@ -1741,8 +1767,21 @@ function cmdReleaseCut(argv) {
|
|
|
1741
1767
|
if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
|
|
1742
1768
|
}
|
|
1743
1769
|
|
|
1770
|
+
// #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
|
|
1771
|
+
// later commit, on a final route, or under a candidates-per-day cap. Null at the head: today's cut.
|
|
1772
|
+
let qualified = null;
|
|
1773
|
+
if (sha !== head) {
|
|
1774
|
+
const c = git.git(['tag', '--contains', sha], repoAbs);
|
|
1775
|
+
const atSha = new Set(tagsAtSha);
|
|
1776
|
+
const newer = c.ok ? lines(c).filter(onRemote).filter((t) => !atSha.has(t) && /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t)) : null;
|
|
1777
|
+
qualified = releaseCut.qualifiedShaVerdict({
|
|
1778
|
+
sha, head, newer, finalRoute: fast || library, auto: !!opts.auto,
|
|
1779
|
+
capped: policy.effective && policy.effective.candidatesPerDay !== null && policy.effective.candidatesPerDay !== undefined,
|
|
1780
|
+
});
|
|
1781
|
+
}
|
|
1782
|
+
|
|
1744
1783
|
const verdict = releaseCut.decide({
|
|
1745
|
-
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
|
|
1784
|
+
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy, qualified,
|
|
1746
1785
|
override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
|
|
1747
1786
|
finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
|
|
1748
1787
|
trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
|
|
@@ -1805,7 +1844,7 @@ function cmdReleaseCut(argv) {
|
|
|
1805
1844
|
|
|
1806
1845
|
if (opts.json) {
|
|
1807
1846
|
print(JSON.stringify({
|
|
1808
|
-
repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1847
|
+
repo: shortRepo(repoAbs), sha, ...(sha !== head ? { head } : {}), ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1809
1848
|
ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
|
|
1810
1849
|
overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
|
|
1811
1850
|
// #446: present on every route, so the workflow reads one shape — final on deploy-tag-fast and
|
|
@@ -1817,7 +1856,7 @@ function cmdReleaseCut(argv) {
|
|
|
1817
1856
|
return verdict.ok || verdict.noop ? 0 : 1;
|
|
1818
1857
|
}
|
|
1819
1858
|
|
|
1820
|
-
print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at} (last final: ${lastFinal || 'none'})`);
|
|
1859
|
+
print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at}${sha !== head ? ` (main's head: ${shortSha(head)})` : ''} (last final: ${lastFinal || 'none'})`);
|
|
1821
1860
|
if (verdict.signals) {
|
|
1822
1861
|
print(' signals:');
|
|
1823
1862
|
for (const l of verdict.signals.lines) print(` · ${l}`);
|
|
@@ -1830,7 +1869,7 @@ function cmdReleaseCut(argv) {
|
|
|
1830
1869
|
? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
|
|
1831
1870
|
: library
|
|
1832
1871
|
? '· no-op — nothing owed (the manifest still says the last final), or main\'s head already carries a final; nothing tagged.'
|
|
1833
|
-
: '· no-op — nothing owed, inside the route\'s cadence window,
|
|
1872
|
+
: '· no-op — nothing owed, inside the route\'s cadence window, main\'s head is not a promotion of trunk, or a later commit already carries a candidate; nothing cut.');
|
|
1834
1873
|
return 0;
|
|
1835
1874
|
}
|
|
1836
1875
|
if (!verdict.ok) {
|
|
@@ -17353,7 +17392,7 @@ Commands:
|
|
|
17353
17392
|
release-notes [<range>] [--repo P] [--out F] [--headline "..."] grouped Markdown release summary
|
|
17354
17393
|
release-status [<repo>...] [--repo P] [--json] merged-but-UNRELEASED lag on tag-gated repos —
|
|
17355
17394
|
read-only, never tags (#81)
|
|
17356
|
-
release cut [--repo P] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
|
|
17395
|
+
release cut [--repo P] [--sha S] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
|
|
17357
17396
|
vX.Y.Z-rc.N where §6's rung allows it; never a final tag (#338)
|
|
17358
17397
|
release finalize [--repo P] [--tag RC] [--answered-by N] [--dry] [--json] a candidate's next step:
|
|
17359
17398
|
testing / held / new candidate owed / human handoff / final
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
* already-candidate the commit does not already carry a candidate of this version
|
|
24
24
|
* ci-green §6 condition 1 — every run at the sha finished, one succeeded
|
|
25
25
|
* full-suite §6 condition 2 — every workflow that ran at the sha has a successful run
|
|
26
|
+
* (both over the code-verifying runs only, the ship gate's rule — #624)
|
|
26
27
|
* schema-additive §6 condition 3 — no destructive migration since the last final tag
|
|
27
28
|
* switch-dependencies §6 condition 4 — the colab:switch markers are readable, and no finished
|
|
28
29
|
* switch needs one that is still unfinished
|
|
@@ -75,6 +76,7 @@
|
|
|
75
76
|
const migrationPaths = require('./migration-paths');
|
|
76
77
|
const releaseTag = require('./release-tag');
|
|
77
78
|
const { stripCode } = require('./instruction-file');
|
|
79
|
+
const verifyRuns = require('./verify-runs');
|
|
78
80
|
|
|
79
81
|
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
80
82
|
const BUMPS = Object.freeze(['patch', 'minor']);
|
|
@@ -87,7 +89,7 @@ const BUMPS = Object.freeze(['patch', 'minor']);
|
|
|
87
89
|
const RELEASE_BRANCH = 'main';
|
|
88
90
|
|
|
89
91
|
const CONDITIONS = Object.freeze([
|
|
90
|
-
'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
92
|
+
'release-policy', 'cadence', 'spacing', 'promotion', 'qualified-sha', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
91
93
|
...releaseTag.PRE_TAG_CONDITIONS,
|
|
92
94
|
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
93
95
|
'final-grant', 'release-hold', 'migration-grant',
|
|
@@ -515,6 +517,35 @@ function cadenceVerdict({ candidates, perDay, now }) {
|
|
|
515
517
|
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 };
|
|
516
518
|
}
|
|
517
519
|
|
|
520
|
+
// ---- #622: a candidate at a named sha that is not main's head ----------------------------------
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* `release cut --sha <sha>` (#622): a busy trunk moves during every long qualifying suite, so the sha
|
|
524
|
+
* that went green is rarely still main's head when its run ends. The cut may name that sha instead —
|
|
525
|
+
* every other condition is already measured at the sha; this verdict answers only what is new about
|
|
526
|
+
* tagging a commit below the head. Null when the sha IS main's head (nothing new: today's cut).
|
|
527
|
+
*
|
|
528
|
+
* newer release tags (candidate or final) on a commit that DESCENDS from the sha — a CI run
|
|
529
|
+
* finishing out of order. A candidate here would move `next` backwards.
|
|
530
|
+
* finalRoute deploy-tag-fast / library-fast: their cut is a FINAL, and #622 is candidates-only —
|
|
531
|
+
* those routes keep tagging main's head.
|
|
532
|
+
* capped --auto under a declared release.candidates-per-day cap: a capped route spends its
|
|
533
|
+
* cut on the head (#443's "never an older commit").
|
|
534
|
+
*
|
|
535
|
+
* Returns { ok, detail, unread }. Not ok is a NO-OP under --auto (the head's own run cuts), a refusal
|
|
536
|
+
* by hand. `newer: null` = the tags could not be read — unread, never "none newer".
|
|
537
|
+
*/
|
|
538
|
+
function qualifiedShaVerdict({ sha, head, newer, finalRoute = false, capped = false, auto = false }) {
|
|
539
|
+
const s = String(sha || '').slice(0, 7);
|
|
540
|
+
const h = String(head || '').slice(0, 7);
|
|
541
|
+
if (!sha || !head || sha === head) return null;
|
|
542
|
+
if (finalRoute) return { ok: false, detail: `${s} is not main's head (${h}) — this route's cut is a final, and a final is tagged only on main's head; --sha names a candidate (#622)` };
|
|
543
|
+
if (auto && capped) return { ok: false, detail: `${s} is not main's head (${h}) — under a release.candidates-per-day cap a cut is spent on the head, never an older commit (#443)` };
|
|
544
|
+
if (newer === null || newer === undefined) return { ok: false, unread: true, detail: `the release tags on commits after ${s} could not be read — an unread newer candidate is not an absent one` };
|
|
545
|
+
if (newer.length) return { ok: false, detail: `${newer.join(', ')} already names a commit after ${s} — a candidate here would move \`next\` backwards; the newer one stands` };
|
|
546
|
+
return { ok: true, detail: `${s} is below main's head (${h}) and no release tag names a later commit — the candidate is cut at ${s} (#622)` };
|
|
547
|
+
}
|
|
548
|
+
|
|
518
549
|
// ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
|
|
519
550
|
|
|
520
551
|
/**
|
|
@@ -708,6 +739,34 @@ function withoutSkippedOnlyWorkflows(rows) {
|
|
|
708
739
|
return rows.filter((r) => !drop.has((r && r.workflowName) || '(unnamed workflow)'));
|
|
709
740
|
}
|
|
710
741
|
|
|
742
|
+
/**
|
|
743
|
+
* #624: the run rows `release cut` judges ci-green and full-suite over — the runs that VERIFY the code
|
|
744
|
+
* at the sha, by the ship gate's own rule (verify-runs.js, #503: push / pull_request / merge_group
|
|
745
|
+
* triggers, project.yml `ship-gate-workflows` / `ship-ignore-workflows`, the #567 dispatch rescue).
|
|
746
|
+
* One rule for "which workflows may veto", not a second. Measured: a qualified sha whose CI push run
|
|
747
|
+
* had succeeded was refused ci-green AND full-suite because a scheduled `Nightly` run at the same sha
|
|
748
|
+
* was still in progress — a run that comes after the verdict, not part of it. Returns `{ rows,
|
|
749
|
+
* setAside }`; each set-aside row carries `setAsideWhy`. null passes through as `{ rows: null }`.
|
|
750
|
+
*/
|
|
751
|
+
function verifyingRunsForCut(rows, policy) {
|
|
752
|
+
if (!Array.isArray(rows)) return { rows, setAside: [], dispatchCounted: [] };
|
|
753
|
+
const split = verifyRuns.splitVerifying(rows, policy || { gate: null, ignore: [] });
|
|
754
|
+
return { rows: split.counted, setAside: split.setAside, dispatchCounted: split.dispatchCounted || [] };
|
|
755
|
+
}
|
|
756
|
+
|
|
757
|
+
/**
|
|
758
|
+
* #624: the detail suffix naming what `verifyingRunsForCut` set aside (and any lost-push dispatch run
|
|
759
|
+
* it counted, #567) — the ship gate's own wording, so one reader learns one phrase. '' when neither.
|
|
760
|
+
*/
|
|
761
|
+
function verifyingNote(read) {
|
|
762
|
+
if (!read) return '';
|
|
763
|
+
const summary = (list) => (list || []).map((x) => ({
|
|
764
|
+
workflowName: x.workflowName || null, status: x.status || null, conclusion: x.conclusion || null,
|
|
765
|
+
databaseId: x.databaseId || null, ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
|
|
766
|
+
}));
|
|
767
|
+
return verifyRuns.setAsideNote(summary(read.setAside)) + verifyRuns.dispatchCountedNote(summary(read.dispatchCounted));
|
|
768
|
+
}
|
|
769
|
+
|
|
711
770
|
/**
|
|
712
771
|
* The run rows minus the CALLING workflow's own runs (#425). Inside the release workflow
|
|
713
772
|
* (templates/release-auto.yml) `release cut` / `release finalize` read the runs at the very commit
|
|
@@ -1032,6 +1091,14 @@ function decide(facts) {
|
|
|
1032
1091
|
}
|
|
1033
1092
|
}
|
|
1034
1093
|
|
|
1094
|
+
// #622: a cut at a named sha below main's head — only what is new about it; every other row is
|
|
1095
|
+
// already measured at the sha. Null (no row) when the sha is the head or no --sha was given.
|
|
1096
|
+
const q = f.qualified;
|
|
1097
|
+
if (q) {
|
|
1098
|
+
add('qualified-sha', q.ok, q.detail, isUnread(q));
|
|
1099
|
+
if (!q.ok && f.auto && !q.unread) noop = true;
|
|
1100
|
+
}
|
|
1101
|
+
|
|
1035
1102
|
const trig = f.triggers || [];
|
|
1036
1103
|
if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
|
|
1037
1104
|
else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
|
|
@@ -1188,8 +1255,8 @@ module.exports = {
|
|
|
1188
1255
|
CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
1189
1256
|
isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1190
1257
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
1191
|
-
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
1192
|
-
fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
|
|
1258
|
+
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
|
|
1259
|
+
fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, verifyingRunsForCut, verifyingNote, isMigrationPath, schemaVerdict,
|
|
1193
1260
|
parseSwitchMarkers, switchVerdict,
|
|
1194
1261
|
promotionVerdict, decide, tagMessage, versionSourceOf,
|
|
1195
1262
|
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
|