@futurelastic/colab-handbook 1.17.0-rc.3 → 1.17.1-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/tools/colab +35 -19
- package/tools/lib/integration-profile.js +24 -2
- package/tools/lib/ship-batch.js +25 -6
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -1763,8 +1763,8 @@ function cmdReleaseCut(argv) {
|
|
|
1763
1763
|
let heavy = null;
|
|
1764
1764
|
if (fast || library) {
|
|
1765
1765
|
const lane = heavyLaneAt(repoAbs, doc, sha);
|
|
1766
|
-
heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
|
|
1767
|
-
if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
|
|
1766
|
+
heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main', inputs: lane.inputs });
|
|
1767
|
+
if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha, lane.inputs);
|
|
1768
1768
|
}
|
|
1769
1769
|
|
|
1770
1770
|
// #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
|
|
@@ -2084,7 +2084,7 @@ function readRegressionEdges(repoAbs, num) {
|
|
|
2084
2084
|
*/
|
|
2085
2085
|
function releaseHeavyFact(repoAbs, doc, cand) {
|
|
2086
2086
|
const lane = heavyLaneAt(repoAbs, doc, cand.sha);
|
|
2087
|
-
return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
|
|
2087
|
+
return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag, inputs: lane.inputs });
|
|
2088
2088
|
}
|
|
2089
2089
|
|
|
2090
2090
|
function cmdReleaseFinalize(argv) {
|
|
@@ -11104,8 +11104,11 @@ It never waits: each call reads the remote, takes ONE step and exits —
|
|
|
11104
11104
|
NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
|
|
11105
11105
|
re-running hits the same refusal until its cause is fixed (#509)
|
|
11106
11106
|
One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
|
|
11107
|
-
is pending or green
|
|
11108
|
-
for is built in its place, so the survivors of a
|
|
11107
|
+
is pending, or green within ${shipBatch.LANE_GRACE_SEC / 60}m of settling (the serial doors' lane grace, below), but a declined one — its
|
|
11108
|
+
combined run red — is deleted and the batch you asked for is built in its place, so the survivors of a
|
|
11109
|
+
decline can batch without landing serially first (#391). A green one still unlanded past that grace lost
|
|
11110
|
+
its lander and is deleted and rebuilt the same way; a green one whose settle time cannot be read is
|
|
11111
|
+
still waited on — only a provably abandoned batch is deleted (#659).
|
|
11109
11112
|
A call that goes serial on trunk CI not green gives up on its members, so it deletes every batch at
|
|
11110
11113
|
trunk's tip whose members it ALL names (its run cancelled if still going) — nobody would ever land
|
|
11111
11114
|
it, and it would hold this base for every later call; a batch also carrying another member stays (#656).
|
|
@@ -14399,7 +14402,7 @@ function cmdShip(argv) {
|
|
|
14399
14402
|
// ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
|
|
14400
14403
|
if (heavyGate && !heavyGate.ok) {
|
|
14401
14404
|
print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
|
|
14402
|
-
if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
|
|
14405
|
+
if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha, heavyGate.inputs);
|
|
14403
14406
|
else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
|
|
14404
14407
|
return 3;
|
|
14405
14408
|
}
|
|
@@ -15186,7 +15189,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
|
15186
15189
|
function heavyLaneAt(repoAbs, doc, sha) {
|
|
15187
15190
|
const file = integrationProfile.parseHeavyWorkflow(doc).file;
|
|
15188
15191
|
const rel = `.github/workflows/${file}`;
|
|
15189
|
-
let present = false, name = rel;
|
|
15192
|
+
let present = false, name = rel, inputs = null;
|
|
15190
15193
|
if (sha) {
|
|
15191
15194
|
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
|
|
15192
15195
|
const show = git.git(['show', `${sha}:${rel}`], repoAbs);
|
|
@@ -15194,11 +15197,12 @@ function heavyLaneAt(repoAbs, doc, sha) {
|
|
|
15194
15197
|
present = true;
|
|
15195
15198
|
const t = verifyRuns.workflowTriggers(show.stdout);
|
|
15196
15199
|
if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
|
|
15200
|
+
inputs = workflowTriggers.workflowDispatchInputs(show.stdout); // #660: which -f flags it accepts
|
|
15197
15201
|
}
|
|
15198
15202
|
}
|
|
15199
15203
|
const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
|
|
15200
15204
|
const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
|
|
15201
|
-
return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
|
|
15205
|
+
return { file, name, present, inputs, verdict: integrationProfile.heavyVerdict(heavyRows) };
|
|
15202
15206
|
}
|
|
15203
15207
|
|
|
15204
15208
|
/**
|
|
@@ -15218,14 +15222,18 @@ function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMem
|
|
|
15218
15222
|
}
|
|
15219
15223
|
const lane = heavyLaneAt(repoAbs, doc, sha);
|
|
15220
15224
|
const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
|
|
15221
|
-
return { ...gate, sha, file: lane.file, name: lane.name };
|
|
15225
|
+
return { ...gate, sha, file: lane.file, name: lane.name, inputs: lane.inputs };
|
|
15222
15226
|
}
|
|
15223
15227
|
|
|
15224
|
-
/**
|
|
15225
|
-
|
|
15226
|
-
|
|
15228
|
+
/**
|
|
15229
|
+
* #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits.
|
|
15230
|
+
* #660: `-f ref=<sha>` only where the workflow declares a `ref` dispatch input (`inputs`, read at the
|
|
15231
|
+
* sha by heavyLaneAt); a repo's own copy may not, and GitHub answers an undeclared input with a 422.
|
|
15232
|
+
*/
|
|
15233
|
+
function dispatchHeavyLane(repoAbs, file, ref, sha, inputs) {
|
|
15234
|
+
const d = git.ghWorkflowDispatch(repoAbs, file, ref, integrationProfile.takesRefInput(inputs) ? { ref: sha } : {});
|
|
15227
15235
|
if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
|
|
15228
|
-
else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself:
|
|
15236
|
+
else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: ${integrationProfile.heavyStartCommand({ file, ref, input: sha, inputs })}`);
|
|
15229
15237
|
return d.ok;
|
|
15230
15238
|
}
|
|
15231
15239
|
|
|
@@ -15483,15 +15491,23 @@ function cmdShipBatch(opts) {
|
|
|
15483
15491
|
const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
|
|
15484
15492
|
const foreign = inBatch.filter((m) => !members.includes(m.branch));
|
|
15485
15493
|
// #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
|
|
15486
|
-
|
|
15494
|
+
// #659: nor is a green one past the lane grace (laneHold's rule) — its lander is gone.
|
|
15495
|
+
let foreignStep = null;
|
|
15496
|
+
if (foreign.length) {
|
|
15497
|
+
const runs = git.ghRunsForRef(repoAbs, atBase.parsed.ref, atBase.sha);
|
|
15498
|
+
foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs), { settledAtMs: shipBatch.settledAt(runs), nowMs: Date.now() });
|
|
15499
|
+
}
|
|
15487
15500
|
if (foreignStep && foreignStep.step === 'wait') {
|
|
15488
|
-
print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}.`);
|
|
15501
|
+
print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}${foreignStep.why ? ` (${foreignStep.why})` : ''}.`);
|
|
15489
15502
|
print(' Wait for it to land or be declined, then run this command again.');
|
|
15490
15503
|
return 3;
|
|
15491
15504
|
}
|
|
15492
15505
|
if (foreignStep) {
|
|
15493
|
-
|
|
15494
|
-
|
|
15506
|
+
const carried = inBatch.map((m) => m.branch).join(', ');
|
|
15507
|
+
print(foreignStep.reason === 'abandoned'
|
|
15508
|
+
? ` ${atBase.parsed.ref} (${carried}) was abandoned — its ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch.`
|
|
15509
|
+
: ` ${atBase.parsed.ref} (${carried}) was declined — its combined run is red (${foreignStep.why}); nothing landed from it. Deleting it and building the requested batch.`);
|
|
15510
|
+
if (!opts.dry && !deleteRef(atBase.parsed.ref)) throw new UserError(`could not clear the ${foreignStep.reason === 'abandoned' ? 'abandoned' : 'declined'} ${atBase.parsed.ref} — delete it by hand (\`git push ${remote} --delete ${atBase.parsed.ref}\`), then run this command again`);
|
|
15495
15511
|
}
|
|
15496
15512
|
if (!foreignStep) {
|
|
15497
15513
|
const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
|
|
@@ -15538,7 +15554,7 @@ function cmdShipBatch(opts) {
|
|
|
15538
15554
|
}
|
|
15539
15555
|
if (step.step === 'wait-run') {
|
|
15540
15556
|
print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
|
|
15541
|
-
if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
|
|
15557
|
+
if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha, heavyWave.inputs); // #610
|
|
15542
15558
|
print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
|
|
15543
15559
|
return 3;
|
|
15544
15560
|
}
|
|
@@ -17328,7 +17344,7 @@ function cmdPromote(argv) {
|
|
|
17328
17344
|
if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
|
|
17329
17345
|
else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
|
|
17330
17346
|
else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
|
|
17331
|
-
else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it:
|
|
17347
|
+
else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: ${integrationProfile.heavyStartCommand({ file: lane.file, ref: trunk, input: tip, inputs: lane.inputs })}` : ''}`; }
|
|
17332
17348
|
checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
|
|
17333
17349
|
}
|
|
17334
17350
|
|
|
@@ -134,6 +134,27 @@ function waveVerdict(light, heavy) {
|
|
|
134
134
|
return { ...light, state: 'pending', heavyMissing: heavy.state === 'none', why: `light green; heavy lane: ${heavy.why}` };
|
|
135
135
|
}
|
|
136
136
|
|
|
137
|
+
/**
|
|
138
|
+
* #660: does the heavy workflow take a `ref` dispatch input? `inputs` is the list of names its
|
|
139
|
+
* `on: workflow_dispatch: inputs:` declares at the ref being dispatched (workflow-triggers.js
|
|
140
|
+
* workflowDispatchInputs). The template declares `ref`, but a repo owns its copy and may not: passing
|
|
141
|
+
* `-f ref=` to a workflow without that input is a hard `HTTP 422: Unexpected inputs provided`. Not an
|
|
142
|
+
* array → the file was not read, so the template's shape is assumed (the pre-#660 behaviour).
|
|
143
|
+
*/
|
|
144
|
+
function takesRefInput(inputs) {
|
|
145
|
+
return !Array.isArray(inputs) || inputs.includes('ref');
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* #660: the command that starts the heavy lane on `ref` — `-f ref=<input>` only where the workflow
|
|
150
|
+
* declares that input (`input` defaults to `ref`). Without it, `--ref` alone is what checks out the
|
|
151
|
+
* code, which for a tag or a branch head is the same commit.
|
|
152
|
+
*/
|
|
153
|
+
function heavyStartCommand({ file, ref, input, inputs }) {
|
|
154
|
+
const base = `gh workflow run ${file} --ref ${ref}`;
|
|
155
|
+
return takesRefInput(inputs) ? `${base} -f ref=${input || ref}` : base;
|
|
156
|
+
}
|
|
157
|
+
|
|
137
158
|
/**
|
|
138
159
|
* The final release's heavy-lane condition — under EVERY profile (#610). A repo with no heavy lane at
|
|
139
160
|
* the candidate has nothing to gate (#607's templates say the same: "no heavy lane here → no gate"),
|
|
@@ -143,11 +164,11 @@ function waveVerdict(light, heavy) {
|
|
|
143
164
|
* candidate; by hand: the printed command).
|
|
144
165
|
* → { ok, pending, detail }
|
|
145
166
|
*/
|
|
146
|
-
function releaseHeavyCondition({ present, file, verdict, at, ref }) {
|
|
167
|
+
function releaseHeavyCondition({ present, file, verdict, at, ref, inputs }) {
|
|
147
168
|
if (!present) return { ok: true, pending: false, detail: `no .github/workflows/${file} at ${at} — no heavy lane in this repo, nothing to gate` };
|
|
148
169
|
const v = verdict || { state: 'unread', why: 'not read' };
|
|
149
170
|
const link = v.url ? ` (${v.url})` : '';
|
|
150
|
-
const start =
|
|
171
|
+
const start = heavyStartCommand({ file, ref: ref || '<the candidate tag>', inputs });
|
|
151
172
|
if (v.state === 'green') return { ok: true, pending: false, detail: `heavy lane green at ${at}${link}` };
|
|
152
173
|
if (v.state === 'red') return { ok: false, pending: false, detail: `heavy lane red at ${at}${link} — a final needs it green at this exact sha: re-run it green, or cut a new candidate` };
|
|
153
174
|
if (v.state === 'pending') return { ok: false, pending: true, detail: `heavy lane still running at ${at}${link} — no final until it is green` };
|
|
@@ -158,4 +179,5 @@ function releaseHeavyCondition({ present, file, verdict, at, ref }) {
|
|
|
158
179
|
module.exports = {
|
|
159
180
|
KEY, HEAVY_KEY, PROFILES, DEFAULT_PROFILE, DEFAULT_HEAVY_WORKFLOW,
|
|
160
181
|
parseProfile, parseHeavyWorkflow, heavyVerdict, liveRestriction, landingGate, waveVerdict, releaseHeavyCondition,
|
|
182
|
+
takesRefInput, heavyStartCommand,
|
|
161
183
|
};
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -462,12 +462,30 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
|
|
|
462
462
|
* for. Is it still in flight, or already declined? Only a pending/green (or not-yet-run) batch is in
|
|
463
463
|
* flight and may make the new request wait; a red one — first attempt or after its re-run — has
|
|
464
464
|
* been declined (`red-rerun-or-serial` keeps its ref so the one re-run stays possible), and keeping
|
|
465
|
-
* it would block every later batch at this base until trunk moved.
|
|
466
|
-
*
|
|
467
|
-
*
|
|
465
|
+
* it would block every later batch at this base until trunk moved.
|
|
466
|
+
*
|
|
467
|
+
* #659: a GREEN one is in flight only for the grace the serial doors give it (laneHold): its lander
|
|
468
|
+
* lands it on its next call, so a green ref still at trunk's tip `graceSec` after its run settled has
|
|
469
|
+
* lost its lander (died after green, before the fast-forward) and would pause every batch at this
|
|
470
|
+
* base until trunk moved for some other reason — while the serial doors already release it. So:
|
|
471
|
+
* clear red → `reason: 'red'`; green, settled ≥ graceSec ago → `reason: 'abandoned'`
|
|
472
|
+
* → delete the ref, then build the requested batch
|
|
473
|
+
* wait anything else → exit 3: pending, none, green within the grace — and green whose settle
|
|
474
|
+
* time could not be read. That last one deliberately differs from laneHold, which releases
|
|
475
|
+
* it: deleting another caller's green run is not undoable, so the batch door clears only a
|
|
476
|
+
* provably abandoned ref (#391's pinned case, kept on purpose — recorded on #659).
|
|
477
|
+
* `settledAtMs` is settledAt() of the ref's runs; `nowMs` the clock.
|
|
468
478
|
*/
|
|
469
|
-
function foreignBatchStep(verdict) {
|
|
470
|
-
|
|
479
|
+
function foreignBatchStep(verdict, { settledAtMs = null, nowMs = null, graceSec = LANE_GRACE_SEC } = {}) {
|
|
480
|
+
if (verdict && verdict.state === 'red') return { step: 'clear', reason: 'red', why: verdict.why };
|
|
481
|
+
if (verdict && verdict.state === 'green' && Number.isFinite(settledAtMs) && Number.isFinite(nowMs)) {
|
|
482
|
+
const mins = Math.max(0, Math.round((nowMs - settledAtMs) / 60000));
|
|
483
|
+
if ((nowMs - settledAtMs) >= graceSec * 1000) {
|
|
484
|
+
return { step: 'clear', reason: 'abandoned', why: `combined run green ${mins}m ago and still not landed (grace ${graceSec}s) — treated as abandoned` };
|
|
485
|
+
}
|
|
486
|
+
return { step: 'wait', why: `combined run green ${mins}m ago — its lander lands it on its next call; past ${Math.round(graceSec / 60)}m unlanded it is cleared` };
|
|
487
|
+
}
|
|
488
|
+
return { step: 'wait' };
|
|
471
489
|
}
|
|
472
490
|
|
|
473
491
|
/**
|
|
@@ -475,7 +493,8 @@ function foreignBatchStep(verdict) {
|
|
|
475
493
|
* green) is giving up on its members — they go to `colab ship --branch`, one at a time. A ref it
|
|
476
494
|
* staged on an earlier call is then landed by nobody: no caller names that set again, and the ref
|
|
477
495
|
* still reads "in flight" to the next `--batch` at the same base (foreignBatchStep waits on a green
|
|
478
|
-
* ref forever) and to the serial doors (laneHold).
|
|
496
|
+
* ref for LANE_GRACE_SEC since #659 — forever before it) and to the serial doors (laneHold).
|
|
497
|
+
* Measured: one repo paused 14 h on such a ref.
|
|
479
498
|
*
|
|
480
499
|
* Which refs this call abandons: those whose carried members are ALL named by this call. A ref that
|
|
481
500
|
* also carries a member this call does not name belongs, at least in part, to another caller — it
|