@futurelastic/colab-handbook 1.14.1-rc.9 → 1.15.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/README.md +1 -1
- package/templates/release-auto.yml +29 -2
- package/tools/colab +41 -11
- package/tools/lib/release-cut.js +39 -2
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.
|
|
@@ -1370,6 +1370,14 @@ The bump (without --auto) is release-status's semverSuggestion since the last fi
|
|
|
1370
1370
|
patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
|
|
1371
1371
|
--bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
|
|
1372
1372
|
--reason "<why>" why the override
|
|
1373
|
+
--sha <sha> (#622) cut at this commit instead of main's head — the qualified sha a busy trunk
|
|
1374
|
+
has already moved past. Every condition above is measured at it; on-trunk
|
|
1375
|
+
requires it on main. One more row when it is not the head:
|
|
1376
|
+
qualified-sha refused (a NO-OP under --auto) when a release tag already names a
|
|
1377
|
+
later commit (the newer candidate stands), on a final route (a
|
|
1378
|
+
final is tagged only on main's head), or --auto under a
|
|
1379
|
+
candidates-per-day cap (the cut is spent on the head)
|
|
1380
|
+
The release workflow passes the sha its triggering CI run tested.
|
|
1373
1381
|
--dry measure and report; create and push nothing
|
|
1374
1382
|
--json machine-readable: { ok, tag, created, checks: [{condition, ok, detail}], ... }
|
|
1375
1383
|
--repo <path> the repo (default: the one you are in)
|
|
@@ -1655,10 +1663,11 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
|
|
|
1655
1663
|
|
|
1656
1664
|
function cmdReleaseCut(argv) {
|
|
1657
1665
|
const opts = parseArgs(argv, {
|
|
1658
|
-
values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
|
|
1666
|
+
values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason', '--sha': 'sha' },
|
|
1659
1667
|
flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
|
|
1660
1668
|
});
|
|
1661
1669
|
if (opts.help) return print(HELP_RELEASE_CUT);
|
|
1670
|
+
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
1671
|
if (opts._.length) throw new UserError(`release cut takes no positional arguments (got: ${opts._.join(' ')})`);
|
|
1663
1672
|
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
1673
|
if (opts.reason && !opts.bump) throw new UserError('--reason records why --bump overrode the computed bump — pass --bump with it');
|
|
@@ -1678,7 +1687,15 @@ function cmdReleaseCut(argv) {
|
|
|
1678
1687
|
const trunkFetch = offTrunk && opts.auto ? git.git(['fetch', remote, trunk], repoAbs) : null;
|
|
1679
1688
|
const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
|
|
1680
1689
|
if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — candidates are cut from main (CONVENTIONS.md §6: never from dev)`);
|
|
1681
|
-
const
|
|
1690
|
+
const head = shaR.stdout;
|
|
1691
|
+
// #622: --sha names the commit to cut — a qualified sha a busy trunk has already moved past. Every
|
|
1692
|
+
// condition below is measured at it; on-trunk still requires it to be an ancestor of main.
|
|
1693
|
+
let sha = head;
|
|
1694
|
+
if (opts.sha) {
|
|
1695
|
+
const r = git.git(['rev-parse', '--verify', '--quiet', `${opts.sha}^{commit}`], repoAbs);
|
|
1696
|
+
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`);
|
|
1697
|
+
sha = r.stdout;
|
|
1698
|
+
}
|
|
1682
1699
|
const at = `main@${shortSha(sha)}`;
|
|
1683
1700
|
|
|
1684
1701
|
const wf = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
|
|
@@ -1695,7 +1712,7 @@ function cmdReleaseCut(argv) {
|
|
|
1695
1712
|
const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
|
|
1696
1713
|
const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
|
|
1697
1714
|
const suggestion = lastFinal
|
|
1698
|
-
? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${
|
|
1715
|
+
? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${sha}`)) // #622: the bump reads what the tagged commit carries
|
|
1699
1716
|
: { bump: null, why: 'no final tag yet' };
|
|
1700
1717
|
const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
|
|
1701
1718
|
const onRemote = (t) => remoteTags.has(t);
|
|
@@ -1741,8 +1758,21 @@ function cmdReleaseCut(argv) {
|
|
|
1741
1758
|
if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
|
|
1742
1759
|
}
|
|
1743
1760
|
|
|
1761
|
+
// #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
|
|
1762
|
+
// later commit, on a final route, or under a candidates-per-day cap. Null at the head: today's cut.
|
|
1763
|
+
let qualified = null;
|
|
1764
|
+
if (sha !== head) {
|
|
1765
|
+
const c = git.git(['tag', '--contains', sha], repoAbs);
|
|
1766
|
+
const atSha = new Set(tagsAtSha);
|
|
1767
|
+
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;
|
|
1768
|
+
qualified = releaseCut.qualifiedShaVerdict({
|
|
1769
|
+
sha, head, newer, finalRoute: fast || library, auto: !!opts.auto,
|
|
1770
|
+
capped: policy.effective && policy.effective.candidatesPerDay !== null && policy.effective.candidatesPerDay !== undefined,
|
|
1771
|
+
});
|
|
1772
|
+
}
|
|
1773
|
+
|
|
1744
1774
|
const verdict = releaseCut.decide({
|
|
1745
|
-
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
|
|
1775
|
+
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy, qualified,
|
|
1746
1776
|
override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
|
|
1747
1777
|
finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
|
|
1748
1778
|
trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
|
|
@@ -1805,7 +1835,7 @@ function cmdReleaseCut(argv) {
|
|
|
1805
1835
|
|
|
1806
1836
|
if (opts.json) {
|
|
1807
1837
|
print(JSON.stringify({
|
|
1808
|
-
repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1838
|
+
repo: shortRepo(repoAbs), sha, ...(sha !== head ? { head } : {}), ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1809
1839
|
ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
|
|
1810
1840
|
overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
|
|
1811
1841
|
// #446: present on every route, so the workflow reads one shape — final on deploy-tag-fast and
|
|
@@ -1817,7 +1847,7 @@ function cmdReleaseCut(argv) {
|
|
|
1817
1847
|
return verdict.ok || verdict.noop ? 0 : 1;
|
|
1818
1848
|
}
|
|
1819
1849
|
|
|
1820
|
-
print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at} (last final: ${lastFinal || 'none'})`);
|
|
1850
|
+
print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at}${sha !== head ? ` (main's head: ${shortSha(head)})` : ''} (last final: ${lastFinal || 'none'})`);
|
|
1821
1851
|
if (verdict.signals) {
|
|
1822
1852
|
print(' signals:');
|
|
1823
1853
|
for (const l of verdict.signals.lines) print(` · ${l}`);
|
|
@@ -1830,7 +1860,7 @@ function cmdReleaseCut(argv) {
|
|
|
1830
1860
|
? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
|
|
1831
1861
|
: library
|
|
1832
1862
|
? '· 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,
|
|
1863
|
+
: '· 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
1864
|
return 0;
|
|
1835
1865
|
}
|
|
1836
1866
|
if (!verdict.ok) {
|
|
@@ -17353,7 +17383,7 @@ Commands:
|
|
|
17353
17383
|
release-notes [<range>] [--repo P] [--out F] [--headline "..."] grouped Markdown release summary
|
|
17354
17384
|
release-status [<repo>...] [--repo P] [--json] merged-but-UNRELEASED lag on tag-gated repos —
|
|
17355
17385
|
read-only, never tags (#81)
|
|
17356
|
-
release cut [--repo P] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
|
|
17386
|
+
release cut [--repo P] [--sha S] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
|
|
17357
17387
|
vX.Y.Z-rc.N where §6's rung allows it; never a final tag (#338)
|
|
17358
17388
|
release finalize [--repo P] [--tag RC] [--answered-by N] [--dry] [--json] a candidate's next step:
|
|
17359
17389
|
testing / held / new candidate owed / human handoff / final
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -87,7 +87,7 @@ const BUMPS = Object.freeze(['patch', 'minor']);
|
|
|
87
87
|
const RELEASE_BRANCH = 'main';
|
|
88
88
|
|
|
89
89
|
const CONDITIONS = Object.freeze([
|
|
90
|
-
'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
90
|
+
'release-policy', 'cadence', 'spacing', 'promotion', 'qualified-sha', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
|
|
91
91
|
...releaseTag.PRE_TAG_CONDITIONS,
|
|
92
92
|
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
93
93
|
'final-grant', 'release-hold', 'migration-grant',
|
|
@@ -515,6 +515,35 @@ function cadenceVerdict({ candidates, perDay, now }) {
|
|
|
515
515
|
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
516
|
}
|
|
517
517
|
|
|
518
|
+
// ---- #622: a candidate at a named sha that is not main's head ----------------------------------
|
|
519
|
+
|
|
520
|
+
/**
|
|
521
|
+
* `release cut --sha <sha>` (#622): a busy trunk moves during every long qualifying suite, so the sha
|
|
522
|
+
* that went green is rarely still main's head when its run ends. The cut may name that sha instead —
|
|
523
|
+
* every other condition is already measured at the sha; this verdict answers only what is new about
|
|
524
|
+
* tagging a commit below the head. Null when the sha IS main's head (nothing new: today's cut).
|
|
525
|
+
*
|
|
526
|
+
* newer release tags (candidate or final) on a commit that DESCENDS from the sha — a CI run
|
|
527
|
+
* finishing out of order. A candidate here would move `next` backwards.
|
|
528
|
+
* finalRoute deploy-tag-fast / library-fast: their cut is a FINAL, and #622 is candidates-only —
|
|
529
|
+
* those routes keep tagging main's head.
|
|
530
|
+
* capped --auto under a declared release.candidates-per-day cap: a capped route spends its
|
|
531
|
+
* cut on the head (#443's "never an older commit").
|
|
532
|
+
*
|
|
533
|
+
* Returns { ok, detail, unread }. Not ok is a NO-OP under --auto (the head's own run cuts), a refusal
|
|
534
|
+
* by hand. `newer: null` = the tags could not be read — unread, never "none newer".
|
|
535
|
+
*/
|
|
536
|
+
function qualifiedShaVerdict({ sha, head, newer, finalRoute = false, capped = false, auto = false }) {
|
|
537
|
+
const s = String(sha || '').slice(0, 7);
|
|
538
|
+
const h = String(head || '').slice(0, 7);
|
|
539
|
+
if (!sha || !head || sha === head) return null;
|
|
540
|
+
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)` };
|
|
541
|
+
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)` };
|
|
542
|
+
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` };
|
|
543
|
+
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` };
|
|
544
|
+
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)` };
|
|
545
|
+
}
|
|
546
|
+
|
|
518
547
|
// ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
|
|
519
548
|
|
|
520
549
|
/**
|
|
@@ -1032,6 +1061,14 @@ function decide(facts) {
|
|
|
1032
1061
|
}
|
|
1033
1062
|
}
|
|
1034
1063
|
|
|
1064
|
+
// #622: a cut at a named sha below main's head — only what is new about it; every other row is
|
|
1065
|
+
// already measured at the sha. Null (no row) when the sha is the head or no --sha was given.
|
|
1066
|
+
const q = f.qualified;
|
|
1067
|
+
if (q) {
|
|
1068
|
+
add('qualified-sha', q.ok, q.detail, isUnread(q));
|
|
1069
|
+
if (!q.ok && f.auto && !q.unread) noop = true;
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1035
1072
|
const trig = f.triggers || [];
|
|
1036
1073
|
if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
|
|
1037
1074
|
else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
|
|
@@ -1188,7 +1225,7 @@ module.exports = {
|
|
|
1188
1225
|
CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
1189
1226
|
isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1190
1227
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
1191
|
-
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
1228
|
+
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
|
|
1192
1229
|
fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
|
|
1193
1230
|
parseSwitchMarkers, switchVerdict,
|
|
1194
1231
|
promotionVerdict, decide, tagMessage, versionSourceOf,
|