@futurelastic/colab-handbook 1.13.0-rc.22 → 1.13.0-rc.24
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 +11 -0
- package/package.json +1 -1
- package/templates/ci-laravel.yml +21 -5
- package/templates/ci-node.yml +23 -6
- package/templates/ci-python.yml +23 -6
- package/tools/colab +46 -12
- package/tools/lib/ci-wait.js +2 -0
- package/tools/lib/git.js +2 -1
- package/tools/lib/release-finalize.js +37 -9
- package/tools/lib/ship-batch.js +66 -2
package/audit/audit.mjs
CHANGED
|
@@ -1304,6 +1304,17 @@ function auditRepo(target, ctx) {
|
|
|
1304
1304
|
}
|
|
1305
1305
|
}
|
|
1306
1306
|
|
|
1307
|
+
// ---- ship-batch-wait (#555) -------------------------------------------------
|
|
1308
|
+
// How long a lone ready candidate waits for a partner (tools/lib/ship-batch.js parseShipBatchWait,
|
|
1309
|
+
// the reading `colab ship --batch` uses). Malformed fails here and in the CI templates' descriptor
|
|
1310
|
+
// check, the #416 pattern — ship fails closed to no wait, silently. A window with no batch to fill
|
|
1311
|
+
// (ship-batch absent or 1) is inert, so it warns. No ceiling: the repo chooses the value.
|
|
1312
|
+
if ("ship-batch-wait" in (cfg || {}) && cfg["ship-batch-wait"] !== null) {
|
|
1313
|
+
const wCfg = shipBatch.parseShipBatchWait(cfg);
|
|
1314
|
+
if (!wCfg.valid) fail(`${wCfg.reason} — see project.schema.md, ship-batch-wait`);
|
|
1315
|
+
else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
|
|
1316
|
+
}
|
|
1317
|
+
|
|
1307
1318
|
// ---- migrations (#383) ----------------------------------------------------
|
|
1308
1319
|
// Where the repo's migrations live, beyond the two defaults (database/migrations/,
|
|
1309
1320
|
// prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
|
package/package.json
CHANGED
package/templates/ci-laravel.yml
CHANGED
|
@@ -263,23 +263,39 @@ jobs:
|
|
|
263
263
|
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
264
264
|
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
265
265
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
266
|
-
# cap is 3: project.schema.md, `ship-batch`.
|
|
266
|
+
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
267
|
+
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
267
268
|
# ---------------------------------------------------------------------------
|
|
268
269
|
- name: Descriptor check (.github/project.yml)
|
|
269
270
|
working-directory: ${{ github.workspace }}
|
|
270
271
|
run: |
|
|
271
272
|
[ -f .github/project.yml ] || exit 0
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
273
|
+
# The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
|
|
274
|
+
field() {
|
|
275
|
+
grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
|
|
276
|
+
| sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
|
|
275
277
|
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
276
|
-
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/"
|
|
278
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
|
|
279
|
+
}
|
|
280
|
+
v="$(field ship-batch)"
|
|
277
281
|
case "$v" in
|
|
278
282
|
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
279
283
|
*)
|
|
280
284
|
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
281
285
|
exit 1 ;;
|
|
282
286
|
esac
|
|
287
|
+
# ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
|
|
288
|
+
w="$(field ship-batch-wait)"
|
|
289
|
+
case "$w" in
|
|
290
|
+
''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
|
|
291
|
+
*)
|
|
292
|
+
if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
|
|
293
|
+
echo "ship-batch-wait: $w — ok"
|
|
294
|
+
else
|
|
295
|
+
echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
|
|
296
|
+
exit 1
|
|
297
|
+
fi ;;
|
|
298
|
+
esac
|
|
283
299
|
|
|
284
300
|
# ---------------------------------------------------------------------------
|
|
285
301
|
# Toolchain resolution. Precedence, highest first:
|
package/templates/ci-node.yml
CHANGED
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
# `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
|
|
14
14
|
#
|
|
15
15
|
# What it does:
|
|
16
|
-
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416
|
|
16
|
+
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
17
|
+
# ship-batch-wait, #555).
|
|
17
18
|
# 1. Resolve the Node version from declared sources — never a hardcoded default.
|
|
18
19
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
19
20
|
# 3. Install dependencies with the package manager the lockfile implies.
|
|
@@ -257,23 +258,39 @@ jobs:
|
|
|
257
258
|
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
258
259
|
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
259
260
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
260
|
-
# cap is 3: project.schema.md, `ship-batch`.
|
|
261
|
+
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
262
|
+
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
261
263
|
# ---------------------------------------------------------------------------
|
|
262
264
|
- name: Descriptor check (.github/project.yml)
|
|
263
265
|
working-directory: ${{ github.workspace }}
|
|
264
266
|
run: |
|
|
265
267
|
[ -f .github/project.yml ] || exit 0
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
268
|
+
# The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
|
|
269
|
+
field() {
|
|
270
|
+
grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
|
|
271
|
+
| sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
|
|
269
272
|
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
270
|
-
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/"
|
|
273
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
|
|
274
|
+
}
|
|
275
|
+
v="$(field ship-batch)"
|
|
271
276
|
case "$v" in
|
|
272
277
|
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
273
278
|
*)
|
|
274
279
|
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
275
280
|
exit 1 ;;
|
|
276
281
|
esac
|
|
282
|
+
# ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
|
|
283
|
+
w="$(field ship-batch-wait)"
|
|
284
|
+
case "$w" in
|
|
285
|
+
''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
|
|
286
|
+
*)
|
|
287
|
+
if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
|
|
288
|
+
echo "ship-batch-wait: $w — ok"
|
|
289
|
+
else
|
|
290
|
+
echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
|
|
291
|
+
exit 1
|
|
292
|
+
fi ;;
|
|
293
|
+
esac
|
|
277
294
|
|
|
278
295
|
# ---------------------------------------------------------------------------
|
|
279
296
|
# Toolchain resolution. Precedence, highest first:
|
package/templates/ci-python.yml
CHANGED
|
@@ -27,7 +27,8 @@
|
|
|
27
27
|
# NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
|
|
28
28
|
#
|
|
29
29
|
# What it does:
|
|
30
|
-
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416
|
|
30
|
+
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
31
|
+
# ship-batch-wait, #555).
|
|
31
32
|
# 1. Resolve the Python version from declared sources — never a hardcoded default.
|
|
32
33
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
33
34
|
# 3. Install dependencies from whichever manifest the repo actually has.
|
|
@@ -248,23 +249,39 @@ jobs:
|
|
|
248
249
|
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
249
250
|
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
250
251
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
251
|
-
# cap is 3: project.schema.md, `ship-batch`.
|
|
252
|
+
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
253
|
+
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
252
254
|
# ---------------------------------------------------------------------------
|
|
253
255
|
- name: Descriptor check (.github/project.yml)
|
|
254
256
|
working-directory: ${{ github.workspace }}
|
|
255
257
|
run: |
|
|
256
258
|
[ -f .github/project.yml ] || exit 0
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
259
|
+
# The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
|
|
260
|
+
field() {
|
|
261
|
+
grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
|
|
262
|
+
| sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
|
|
260
263
|
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
261
|
-
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/"
|
|
264
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
|
|
265
|
+
}
|
|
266
|
+
v="$(field ship-batch)"
|
|
262
267
|
case "$v" in
|
|
263
268
|
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
264
269
|
*)
|
|
265
270
|
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
266
271
|
exit 1 ;;
|
|
267
272
|
esac
|
|
273
|
+
# ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
|
|
274
|
+
w="$(field ship-batch-wait)"
|
|
275
|
+
case "$w" in
|
|
276
|
+
''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
|
|
277
|
+
*)
|
|
278
|
+
if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
|
|
279
|
+
echo "ship-batch-wait: $w — ok"
|
|
280
|
+
else
|
|
281
|
+
echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
|
|
282
|
+
exit 1
|
|
283
|
+
fi ;;
|
|
284
|
+
esac
|
|
268
285
|
|
|
269
286
|
# ---------------------------------------------------------------------------
|
|
270
287
|
# Toolchain resolution. Precedence, highest first:
|
package/tools/colab
CHANGED
|
@@ -1851,7 +1851,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
|
|
|
1851
1851
|
Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
|
|
1852
1852
|
under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
|
|
1853
1853
|
|
|
1854
|
-
1. fetches tags, picks the newest open candidate (never a hand-made or
|
|
1854
|
+
1. fetches tags, picks the newest open candidate — or the one --tag names (never a hand-made or
|
|
1855
|
+
off-main one);
|
|
1855
1856
|
2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
|
|
1856
1857
|
starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
|
|
1857
1858
|
3. measures, and ends in exactly one state:
|
|
@@ -1884,7 +1885,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1884
1885
|
test-period from max(candidate tag date, tracking issue creation), release: test-period long
|
|
1885
1886
|
trunk-green every run since the period began on main — and on project.yml's trunk: when that is
|
|
1886
1887
|
another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
|
|
1887
|
-
none red — required only where the final is automatic
|
|
1888
|
+
none red — required only where the final is automatic, or for an older --tag (#548)
|
|
1888
1889
|
|
|
1889
1890
|
manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
|
|
1890
1891
|
the final equals every declared manifest version, its commit is on main (a shallow
|
|
@@ -1906,7 +1907,11 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1906
1907
|
never tags: it stops at candidate-ready and posts the one command, number
|
|
1907
1908
|
pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
|
|
1908
1909
|
already-final exit 0 (nothing to do yet is the ordinary output)
|
|
1909
|
-
--tag <rc> pin the candidate a human reviewed
|
|
1910
|
+
--tag <rc> pin the candidate a human reviewed — the newest one, or any OLDER open candidate
|
|
1911
|
+
(#548). An older one is judged on its own clock exactly as --auto judges it: its
|
|
1912
|
+
own test period must have elapsed and trunk-green is read over its own window, on
|
|
1913
|
+
every row; release-hold and regressions as always. Newer candidates stay open
|
|
1914
|
+
for the next version — only versions below the final are closed as superseded
|
|
1910
1915
|
--answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
|
|
1911
1916
|
No field, flag or project.yml value lowers it, and it never shortens a test period.
|
|
1912
1917
|
Where the final is a human act the period is informational anyway, and
|
|
@@ -1982,6 +1987,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
1982
1987
|
const newest = selection.kind === 'candidate' ? selection.candidate : null;
|
|
1983
1988
|
// #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
|
|
1984
1989
|
const walk = opts.auto && policy.effective.final === 'auto' && newest;
|
|
1990
|
+
// #548: --tag naming an older open candidate — judged on its own clock, as the walk judges it.
|
|
1991
|
+
const ownClock = walk || (selection.kind === 'candidate' && !!selection.older);
|
|
1985
1992
|
|
|
1986
1993
|
// ---- the tracking records (one issue read for the whole run) ----
|
|
1987
1994
|
const issues = readAllIssuesForSwitches(repoAbs);
|
|
@@ -2040,7 +2047,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2040
2047
|
return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
|
|
2041
2048
|
}));
|
|
2042
2049
|
const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
|
|
2043
|
-
periodStart: period.start, periodEnd:
|
|
2050
|
+
periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
|
|
2044
2051
|
});
|
|
2045
2052
|
const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
|
|
2046
2053
|
const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
|
|
@@ -2119,7 +2126,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2119
2126
|
const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
|
|
2120
2127
|
if (!opts.dry) {
|
|
2121
2128
|
if (verdict.state === 'finalized') {
|
|
2122
|
-
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)' : ''}`;
|
|
2129
|
+
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)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
|
|
2123
2130
|
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
|
|
2124
2131
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
|
|
2125
2132
|
if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
@@ -2143,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2143
2150
|
const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
|
|
2144
2151
|
comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
|
|
2145
2152
|
? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — no test period on this repo (\`release.test-period: 0d\`, #549): the human's finalize is the test.`
|
|
2146
|
-
:
|
|
2153
|
+
: ownClock
|
|
2147
2154
|
? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its own test period runs ${pNew.start} → ${pNew.endsAt}. A newer candidate does not restart an older one's clock: the newest candidate clean for its own period is finalized (\`--auto\`).`
|
|
2148
2155
|
: `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
|
|
2149
2156
|
}
|
|
@@ -2160,12 +2167,14 @@ function cmdReleaseFinalize(argv) {
|
|
|
2160
2167
|
// #426: every issue the final carries hears which version has it — on the run that tags, and on
|
|
2161
2168
|
// the already-final resume (a run that died between the tag push and these comments finishes them).
|
|
2162
2169
|
if (tagged) announced = announceRelease(cand.version, cand.sha);
|
|
2163
|
-
// Superseded records
|
|
2164
|
-
//
|
|
2165
|
-
//
|
|
2166
|
-
|
|
2170
|
+
// Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
|
|
2171
|
+
// without --auto closed every other open version at once, because only the newest candidate could
|
|
2172
|
+
// ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
|
|
2173
|
+
// to stay open until a final above it exists — closing it earlier refuses that --tag ("closed but
|
|
2174
|
+
// not final"). A newer version's candidates are still on their own clocks either way.
|
|
2175
|
+
if (cand && tagged) {
|
|
2167
2176
|
for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
|
|
2168
|
-
&&
|
|
2177
|
+
&& releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
|
|
2169
2178
|
comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
|
|
2170
2179
|
close(r.number);
|
|
2171
2180
|
}
|
|
@@ -10342,6 +10351,12 @@ at build, added since) is NOT landed with it — the command names both lists an
|
|
|
10342
10351
|
--dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
|
|
10343
10352
|
locally and printed; a staged green batch prints what would land (members, combined run, target sha).
|
|
10344
10353
|
Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
|
|
10354
|
+
PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
|
|
10355
|
+
unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
|
|
10356
|
+
ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
|
|
10357
|
+
since the member became ready (its head CI's last update, else its head commit's date) — then the same
|
|
10358
|
+
call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
|
|
10359
|
+
--batch with all of them. A single named branch is accepted only when the field is set.
|
|
10345
10360
|
|
|
10346
10361
|
B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
|
|
10347
10362
|
does unasked, however certain it is that the content landed: reporting is safe and reversible,
|
|
@@ -13900,7 +13915,10 @@ function cmdShipBatch(opts) {
|
|
|
13900
13915
|
if (String(doc.autonomy || '') !== 'auto-trunk') {
|
|
13901
13916
|
return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
|
|
13902
13917
|
}
|
|
13903
|
-
|
|
13918
|
+
// #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
|
|
13919
|
+
const waitCfg = shipBatch.parseShipBatchWait(doc);
|
|
13920
|
+
if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
|
|
13921
|
+
if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
|
|
13904
13922
|
if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
|
|
13905
13923
|
|
|
13906
13924
|
const remote = git.remoteFor(repoAbs);
|
|
@@ -14039,6 +14057,22 @@ function cmdShipBatch(opts) {
|
|
|
14039
14057
|
e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
|
|
14040
14058
|
const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
|
|
14041
14059
|
step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
|
|
14060
|
+
if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
|
|
14061
|
+
// #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
|
|
14062
|
+
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
14063
|
+
const lone = selected[0];
|
|
14064
|
+
const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
|
|
14065
|
+
const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
|
|
14066
|
+
const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
|
|
14067
|
+
if (pw.wait) {
|
|
14068
|
+
print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
|
|
14069
|
+
print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
|
|
14070
|
+
print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
|
|
14071
|
+
return 3;
|
|
14072
|
+
}
|
|
14073
|
+
const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
|
|
14074
|
+
return serial(`1 member can join and no partner arrived — ${why}`);
|
|
14075
|
+
}
|
|
14042
14076
|
if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
|
|
14043
14077
|
|
|
14044
14078
|
// ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -94,6 +94,8 @@ function restRow(x) {
|
|
|
94
94
|
return {
|
|
95
95
|
headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
|
|
96
96
|
createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
|
|
97
|
+
// #555: a finished run's last update is its completion — when a lone batch member became ready.
|
|
98
|
+
updatedAt: x.updated_at || null,
|
|
97
99
|
event: x.event || null, url: x.html_url || null,
|
|
98
100
|
// #510: the workflow FILE's id — the cure rule's same-workflow test, which a display name cannot answer.
|
|
99
101
|
workflowId: x.workflow_id ?? null,
|
package/tools/lib/git.js
CHANGED
|
@@ -960,7 +960,8 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
960
960
|
// does not own) before it computes a verdict, and can only do that if the row says so.
|
|
961
961
|
// workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
|
|
962
962
|
// id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
|
|
963
|
-
'
|
|
963
|
+
// updatedAt is additive (#555): a finished run's completion time, the lone-member wait's anchor.
|
|
964
|
+
'--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
|
|
964
965
|
if (!r.ok) return null;
|
|
965
966
|
let runs;
|
|
966
967
|
try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
@@ -39,6 +39,12 @@
|
|
|
39
39
|
* On a route whose final is a human act (`deploy-tag`) --auto never tags: it stops at
|
|
40
40
|
* candidate-ready and posts the one command, number pre-filled.
|
|
41
41
|
*
|
|
42
|
+
* `--tag` (#548) may name ANY open candidate, not only the newest, so a human can release what
|
|
43
|
+
* finished testing without trunk freezing for a whole period. An older one is held to the same rule
|
|
44
|
+
* --auto applies to it: its own test period and its own trunk window are required on every row
|
|
45
|
+
* (selectCandidate marks it `older`; decide() reads that). Newer candidates stay open, and a
|
|
46
|
+
* version's record closes as superseded only once a final ABOVE it is tagged.
|
|
47
|
+
*
|
|
42
48
|
* Before ANY final, the three #424 pre-tag checks (release-tag.js preTagChecks) are required:
|
|
43
49
|
* manifest-version, on-trunk, outranks-final.
|
|
44
50
|
*
|
|
@@ -134,6 +140,8 @@ function trackingBody({ version, row, final, testPeriodDays }) {
|
|
|
134
140
|
* { kind: 'already-final', version, detail }
|
|
135
141
|
* { kind: 'refused', detail }
|
|
136
142
|
* { kind: 'candidate', candidate: { tag, version, n, sha, cutAt }, superseded: [version], detail }
|
|
143
|
+
* { kind: 'candidate', older: true, newest: <tag>, … } #548: `pin` names an open candidate that
|
|
144
|
+
* is not the newest — decide() then requires its own test period and trunk window, as --auto does
|
|
137
145
|
*/
|
|
138
146
|
function selectCandidate(tags, pin, remote = 'origin') {
|
|
139
147
|
const all = tags || [];
|
|
@@ -159,16 +167,32 @@ function selectCandidate(tags, pin, remote = 'origin') {
|
|
|
159
167
|
const newest = open[open.length - 1];
|
|
160
168
|
const superseded = [...new Set(open.map((x) => x.p.version).filter((v) => v !== newest.p.version))];
|
|
161
169
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
const
|
|
170
|
+
// #548: --tag may name an OLDER open candidate. It is then judged on its own clock, exactly as
|
|
171
|
+
// --auto judges it (decide() makes test-period and trunk-green over its own window required), so a
|
|
172
|
+
// human can release what finished testing while trunk keeps merging; the newer candidates stay open.
|
|
173
|
+
const chosen = pin ? open.find((x) => x.t.name === pin) : newest;
|
|
174
|
+
if (!chosen) return { kind: 'refused', detail: `--tag ${pin} is not an open candidate` };
|
|
175
|
+
const older = chosen !== newest;
|
|
176
|
+
const t = chosen.t;
|
|
166
177
|
if (!t.annotated || !String(t.subject || '').endsWith(CUT_SUBJECT_SUFFIX)) {
|
|
167
178
|
return { kind: 'refused', detail: `${t.name} was not made by \`colab release cut\` (not an annotated tag whose message ends "${CUT_SUBJECT_SUFFIX}") — a candidate cut by hand is never finalized (CONVENTIONS.md §6)` };
|
|
168
179
|
}
|
|
169
180
|
if (!t.onMain) return { kind: 'refused', detail: `${t.name} (${String(t.sha).slice(0, 7)}) is not on ${remote}/main — candidates are cut from main` };
|
|
170
181
|
if (!t.date || Number.isNaN(Date.parse(t.date))) return { kind: 'refused', detail: `${t.name} has no readable tagger date — the test period cannot be placed` };
|
|
171
182
|
|
|
183
|
+
if (older) {
|
|
184
|
+
// Only versions BELOW the pinned one are superseded by it; a newer version's candidates stay open.
|
|
185
|
+
const below = [...new Set(open.map((x) => x.p.version).filter((v) => compareVersions(v, chosen.p.version) < 0))];
|
|
186
|
+
const newer = open.filter((x) => compareVersions(x.p.version, chosen.p.version) > 0 || (x.p.version === chosen.p.version && x.p.n > chosen.p.n)).map((x) => x.t.name);
|
|
187
|
+
return {
|
|
188
|
+
kind: 'candidate',
|
|
189
|
+
older: true,
|
|
190
|
+
newest: newest.t.name,
|
|
191
|
+
candidate: { tag: t.name, version: chosen.p.version, n: chosen.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
|
|
192
|
+
superseded: below,
|
|
193
|
+
detail: `${t.name} at ${String(t.sha).slice(0, 7)}, cut ${new Date(t.date).toISOString()} — an older candidate, judged on its own clock (newer, still open: ${newer.join(', ')})${below.length ? `; supersedes ${below.join(', ')}` : ''}`,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
172
196
|
return {
|
|
173
197
|
kind: 'candidate',
|
|
174
198
|
candidate: { tag: t.name, version: newest.p.version, n: newest.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
|
|
@@ -523,10 +547,14 @@ function decide(facts) {
|
|
|
523
547
|
}
|
|
524
548
|
const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
|
|
525
549
|
add('regressions', reg.ok, reg.detail);
|
|
550
|
+
// #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
|
|
551
|
+
// --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
|
|
552
|
+
// no longer explains why THIS one, and its own clean period is what does.
|
|
553
|
+
const ownClock = auto || !!s.older;
|
|
526
554
|
const per = f.period || { elapsed: false, detail: 'not measured' };
|
|
527
|
-
add('test-period', per.elapsed, per.detail,
|
|
555
|
+
add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
|
|
528
556
|
const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
|
|
529
|
-
add('trunk-green', tr.ok, tr.detail,
|
|
557
|
+
add('trunk-green', tr.ok, tr.detail, ownClock);
|
|
530
558
|
for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
531
559
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
532
560
|
}
|
|
@@ -539,14 +567,14 @@ function decide(facts) {
|
|
|
539
567
|
}
|
|
540
568
|
|
|
541
569
|
if (held.length) return out('held');
|
|
542
|
-
if ((reg.permanent) || (
|
|
570
|
+
if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
|
|
543
571
|
const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
|
|
544
572
|
if (blocking.length) return out('refused');
|
|
545
|
-
if (
|
|
573
|
+
if (ownClock) {
|
|
546
574
|
if (!tr.ok && !tr.pending) return out('refused');
|
|
547
575
|
if (!per.elapsed || tr.pending) return out('testing');
|
|
548
|
-
return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
549
576
|
}
|
|
577
|
+
if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
550
578
|
if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
|
|
551
579
|
return out('finalized', { finalTag: cand.version });
|
|
552
580
|
}
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -46,6 +46,70 @@ function parseShipBatch(doc) {
|
|
|
46
46
|
return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
+
const WAIT_KEY = 'ship-batch-wait';
|
|
50
|
+
const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
|
|
54
|
+
* before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
|
|
55
|
+
* bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
|
|
56
|
+
*
|
|
57
|
+
* Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
|
|
58
|
+
* (owner, 2026-10-07: "Should not set any hard code number") — the repo chooses, from its own
|
|
59
|
+
* history. Anything malformed FAILS CLOSED to no wait, with the reason: a bad value must never delay
|
|
60
|
+
* a landing. The audit and the CI templates' descriptor check fail the same values.
|
|
61
|
+
*/
|
|
62
|
+
function parseShipBatchWait(doc) {
|
|
63
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, WAIT_KEY);
|
|
64
|
+
if (!has || doc[WAIT_KEY] === null || doc[WAIT_KEY] === undefined) {
|
|
65
|
+
return { sec: 0, declared: false, valid: true, reason: `${WAIT_KEY} absent` };
|
|
66
|
+
}
|
|
67
|
+
const v = doc[WAIT_KEY];
|
|
68
|
+
const m = typeof v === 'string' ? /^(\d+)([smh])$/.exec(v.trim()) : null;
|
|
69
|
+
if (m) {
|
|
70
|
+
const sec = Number(m[1]) * WAIT_UNITS[m[2]];
|
|
71
|
+
if (Number.isSafeInteger(sec)) return { sec, declared: true, valid: true, reason: `${WAIT_KEY}: ${v.trim()}` };
|
|
72
|
+
}
|
|
73
|
+
return { sec: 0, declared: true, valid: false, reason: `${WAIT_KEY} is ${JSON.stringify(v)}, expected a whole number with a unit — 90s, 6m, 1h (omit for no wait)` };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
|
|
78
|
+
* Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
|
|
79
|
+
* already in flight — the lane is otherwise idle by then):
|
|
80
|
+
* n parseShipBatch(doc).n
|
|
81
|
+
* waitSec parseShipBatchWait(doc).sec (0 = absent, zero, or malformed)
|
|
82
|
+
* eligibleCount members that passed their own gates
|
|
83
|
+
* readySinceMs when the lone member became ready — its head CI's last update, else its head
|
|
84
|
+
* commit's date; null = unreadable
|
|
85
|
+
* nowMs the clock
|
|
86
|
+
* Out: `{ wait: true, leftSec }` or `{ wait: false, reason }`. The window is counted from the member's
|
|
87
|
+
* own ready time, not from this call, so the command stays stateless and re-entrant: every call
|
|
88
|
+
* re-derives how much is left, on any machine, and the window can never restart.
|
|
89
|
+
*/
|
|
90
|
+
function partnerWait({ n, waitSec, eligibleCount, readySinceMs, nowMs }) {
|
|
91
|
+
if (!(n > 1)) return { wait: false, reason: 'not-enabled' };
|
|
92
|
+
if (!(waitSec > 0)) return { wait: false, reason: 'no-window' };
|
|
93
|
+
if (eligibleCount !== 1) return { wait: false, reason: eligibleCount > 1 ? 'has-partner' : 'none-ready' };
|
|
94
|
+
if (!Number.isFinite(readySinceMs) || !Number.isFinite(nowMs)) return { wait: false, reason: 'ready-time-unread' };
|
|
95
|
+
const leftSec = Math.ceil(waitSec - Math.max(0, nowMs - readySinceMs) / 1000);
|
|
96
|
+
if (leftSec <= 0) return { wait: false, reason: 'window-elapsed' };
|
|
97
|
+
return { wait: true, leftSec };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* When did a member become ready? The newest `updatedAt` among its finished head runs (a run's last
|
|
102
|
+
* update is its completion), else — no run, because none can arrive — its head commit's date.
|
|
103
|
+
* Null when neither reads; the caller then does not wait.
|
|
104
|
+
*/
|
|
105
|
+
function readySince(rows, commitIso) {
|
|
106
|
+
const done = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
|
|
107
|
+
.map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
|
|
108
|
+
if (done.length) return Math.max(...done);
|
|
109
|
+
const c = Date.parse(commitIso || '');
|
|
110
|
+
return Number.isFinite(c) ? c : null;
|
|
111
|
+
}
|
|
112
|
+
|
|
49
113
|
function batchRefName(baseSha) {
|
|
50
114
|
return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
|
|
51
115
|
}
|
|
@@ -315,8 +379,8 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
|
|
|
315
379
|
}
|
|
316
380
|
|
|
317
381
|
module.exports = {
|
|
318
|
-
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
|
|
319
|
-
parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
382
|
+
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY,
|
|
383
|
+
parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
320
384
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
321
385
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
322
386
|
};
|