@futurelastic/colab-handbook 1.13.0-rc.21 → 1.13.0-rc.23
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 +63 -27
- package/tools/lib/git.js +61 -12
- package/tools/lib/release-finalize.js +37 -9
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -522,8 +522,9 @@ function localClaimConflicts(st, repoAbs, nums, wtName) {
|
|
|
522
522
|
|
|
523
523
|
/**
|
|
524
524
|
* #325 — the claim record every machine can read, whatever the tracker: a branch on the remote whose
|
|
525
|
-
* name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run
|
|
526
|
-
*
|
|
525
|
+
* name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run), or — since
|
|
526
|
+
* #550 — the claim ref `refs/claims/<branch>` that `colab worktree new` pushes the moment it cuts
|
|
527
|
+
* (a ref no CI trigger watches; the branch itself follows at code-wrap). Asked of the remote directly (`ls-remote`, no fetch), so a
|
|
527
528
|
* clone that has never fetched sees exactly what a fresh one would.
|
|
528
529
|
*
|
|
529
530
|
* `mode`:
|
|
@@ -558,7 +559,7 @@ function remoteClaimConflicts(st, repoAbs, nums) {
|
|
|
558
559
|
for (const h of heads.heads) {
|
|
559
560
|
const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
|
|
560
561
|
if (!carried.length || ours(h.branch)) continue;
|
|
561
|
-
for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
|
|
562
|
+
for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha, claimRef: !!h.claimRef });
|
|
562
563
|
}
|
|
563
564
|
return { mode: 'ok', remote, conflicts };
|
|
564
565
|
}
|
|
@@ -667,13 +668,18 @@ function ghClaimConflicts(repoAbs, nums, myLogin, myHost, mySession, comps, myMa
|
|
|
667
668
|
function printRefusal(localConf, ghConf, remoteConf = []) {
|
|
668
669
|
process.stderr.write('✗ Refusing — one or more issues are already claimed:\n');
|
|
669
670
|
for (const c of remoteConf) {
|
|
670
|
-
process.stderr.write(
|
|
671
|
+
process.stderr.write(c.claimRef
|
|
672
|
+
? ` #${c.num} remote: claim ref ${c.remote} ${git.claimRef(c.branch)} @ ${c.sha} carries it (branch not pushed yet), and it is not this machine's (#325, #550)\n`
|
|
673
|
+
: ` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
|
|
671
674
|
}
|
|
672
675
|
if (remoteConf.length) {
|
|
673
676
|
const c = remoteConf[0];
|
|
674
|
-
process.stderr.write(
|
|
675
|
-
process.stderr.write(
|
|
677
|
+
process.stderr.write(` That ${c.claimRef ? 'claim ref' : 'branch'} IS the claim — continue it rather than open a second one:\n`);
|
|
678
|
+
process.stderr.write(c.claimRef
|
|
679
|
+
? ` git fetch ${c.remote} ${git.claimRef(c.branch)}:refs/heads/${c.branch} && git worktree add <path> ${c.branch}\n`
|
|
680
|
+
: ` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
|
|
676
681
|
process.stderr.write(` colab claim ${c.num} --worktree <name> --branch ${c.branch} --session <id> --force\n`);
|
|
682
|
+
if (c.claimRef) process.stderr.write(` A claim ref whose session is gone is stale — delete it: git push ${c.remote} --delete ${git.claimRef(c.branch)}\n`);
|
|
677
683
|
}
|
|
678
684
|
for (const c of localConf) {
|
|
679
685
|
const h = c.holder;
|
|
@@ -710,7 +716,7 @@ function halfClaimText(c) {
|
|
|
710
716
|
/** Announce exactly what --force overrides (a takeover is visible, never silent). */
|
|
711
717
|
function printTakeover(localConf, ghConf, remoteConf = []) {
|
|
712
718
|
for (const c of remoteConf) {
|
|
713
|
-
print(` --force: taking over #${c.num} although branch ${c.remote}/${c.branch} @ ${c.sha} carries it (not this machine's)`);
|
|
719
|
+
print(` --force: taking over #${c.num} although ${c.claimRef ? `claim ref ${c.remote} ${git.claimRef(c.branch)}` : `branch ${c.remote}/${c.branch}`} @ ${c.sha} carries it (not this machine's)`);
|
|
714
720
|
}
|
|
715
721
|
for (const c of localConf) {
|
|
716
722
|
const h = c.holder;
|
|
@@ -877,7 +883,8 @@ const HELP_CLAIM = `colab claim <issue> [<issue> ...] [options]
|
|
|
877
883
|
|
|
878
884
|
Claim one or more GitHub issues so parallel sessions/agents don't collide.
|
|
879
885
|
The claim RECORD every machine reads is a branch on the git remote carrying the issue number
|
|
880
|
-
(\`colab worktree new\`
|
|
886
|
+
(\`colab worktree new\` records it the moment it is cut as the claim ref refs/claims/<branch>,
|
|
887
|
+
which no CI trigger watches — #325, #550). Also writes local state (fast path)
|
|
881
888
|
and the tracker (the copy people read):
|
|
882
889
|
gh issue edit N --add-assignee @me --add-label in-progress
|
|
883
890
|
Remote unreachable → REFUSED (fail closed). Tracker unreachable → the claim stands and its tracker
|
|
@@ -1844,7 +1851,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
|
|
|
1844
1851
|
Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
|
|
1845
1852
|
under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
|
|
1846
1853
|
|
|
1847
|
-
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);
|
|
1848
1856
|
2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
|
|
1849
1857
|
starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
|
|
1850
1858
|
3. measures, and ends in exactly one state:
|
|
@@ -1877,7 +1885,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1877
1885
|
test-period from max(candidate tag date, tracking issue creation), release: test-period long
|
|
1878
1886
|
trunk-green every run since the period began on main — and on project.yml's trunk: when that is
|
|
1879
1887
|
another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
|
|
1880
|
-
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)
|
|
1881
1889
|
|
|
1882
1890
|
manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
|
|
1883
1891
|
the final equals every declared manifest version, its commit is on main (a shallow
|
|
@@ -1899,7 +1907,11 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1899
1907
|
never tags: it stops at candidate-ready and posts the one command, number
|
|
1900
1908
|
pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
|
|
1901
1909
|
already-final exit 0 (nothing to do yet is the ordinary output)
|
|
1902
|
-
--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
|
|
1903
1915
|
--answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
|
|
1904
1916
|
No field, flag or project.yml value lowers it, and it never shortens a test period.
|
|
1905
1917
|
Where the final is a human act the period is informational anyway, and
|
|
@@ -1975,6 +1987,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
1975
1987
|
const newest = selection.kind === 'candidate' ? selection.candidate : null;
|
|
1976
1988
|
// #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
|
|
1977
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);
|
|
1978
1992
|
|
|
1979
1993
|
// ---- the tracking records (one issue read for the whole run) ----
|
|
1980
1994
|
const issues = readAllIssuesForSwitches(repoAbs);
|
|
@@ -2033,7 +2047,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2033
2047
|
return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
|
|
2034
2048
|
}));
|
|
2035
2049
|
const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
|
|
2036
|
-
periodStart: period.start, periodEnd:
|
|
2050
|
+
periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
|
|
2037
2051
|
});
|
|
2038
2052
|
const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
|
|
2039
2053
|
const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
|
|
@@ -2112,7 +2126,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2112
2126
|
const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
|
|
2113
2127
|
if (!opts.dry) {
|
|
2114
2128
|
if (verdict.state === 'finalized') {
|
|
2115
|
-
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})` : ''}`;
|
|
2116
2130
|
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
|
|
2117
2131
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
|
|
2118
2132
|
if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
@@ -2136,7 +2150,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2136
2150
|
const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
|
|
2137
2151
|
comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
|
|
2138
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.`
|
|
2139
|
-
:
|
|
2153
|
+
: ownClock
|
|
2140
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\`).`
|
|
2141
2155
|
: `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
|
|
2142
2156
|
}
|
|
@@ -2153,12 +2167,14 @@ function cmdReleaseFinalize(argv) {
|
|
|
2153
2167
|
// #426: every issue the final carries hears which version has it — on the run that tags, and on
|
|
2154
2168
|
// the already-final resume (a run that died between the tag push and these comments finishes them).
|
|
2155
2169
|
if (tagged) announced = announceRelease(cand.version, cand.sha);
|
|
2156
|
-
// Superseded records
|
|
2157
|
-
//
|
|
2158
|
-
//
|
|
2159
|
-
|
|
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) {
|
|
2160
2176
|
for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
|
|
2161
|
-
&&
|
|
2177
|
+
&& releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
|
|
2162
2178
|
comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
|
|
2163
2179
|
close(r.number);
|
|
2164
2180
|
}
|
|
@@ -5587,23 +5603,30 @@ function cmdWorktreeNew(argv) {
|
|
|
5587
5603
|
// rejected instead of overwriting. With issues to claim, a failed push takes nothing: the worktree
|
|
5588
5604
|
// and the zero-commit branch this invocation just made are removed again, so no half-claim exists
|
|
5589
5605
|
// anywhere. With no issues there is no claim to protect, and a failed push only warns.
|
|
5606
|
+
//
|
|
5607
|
+
// #550: what is pushed is the CLAIM REF `refs/claims/<branch>`, not the branch. A branch push fires
|
|
5608
|
+
// every CI `push` trigger, and at cut the branch IS trunk's commit — so each cut re-ran a suite
|
|
5609
|
+
// trunk had already passed (~27 % of one org's runs). A claim ref triggers nothing, and every
|
|
5610
|
+
// claim reader (`remoteHeads`) lists it beside the branches. The branch itself is first pushed at
|
|
5611
|
+
// code-wrap, when it has commits worth testing. The claim ref is deleted at `worktree rm`.
|
|
5590
5612
|
const pushRemote = git.claimRemote(repoAbs);
|
|
5591
5613
|
let pushed = false;
|
|
5592
5614
|
if (pushRemote) {
|
|
5593
|
-
const
|
|
5615
|
+
const claimRef = git.claimRef(branch);
|
|
5616
|
+
const push = git.pushClaimRef(repoAbs, pushRemote, branch);
|
|
5594
5617
|
if (push.ok) {
|
|
5595
5618
|
pushed = true;
|
|
5596
|
-
print(` pushed ${
|
|
5619
|
+
print(` pushed ${claimRef} → ${pushRemote} (the claim record other machines read; not a branch, so no CI runs — the branch is pushed at code-wrap)`);
|
|
5597
5620
|
} else {
|
|
5598
5621
|
const why = String(push.stderr || '').split('\n').filter(Boolean).slice(-1)[0] || `exit ${push.code}`;
|
|
5599
5622
|
if (issues.length) {
|
|
5600
5623
|
git.git(['worktree', 'remove', '--force', wtPath], repoAbs);
|
|
5601
5624
|
git.git(['branch', '-D', branch], repoAbs);
|
|
5602
|
-
throw new UserError(`git push ${pushRemote} ${
|
|
5603
|
-
'were removed again. The pushed
|
|
5604
|
-
|
|
5625
|
+
throw new UserError(`git push ${pushRemote} ${claimRef} failed (${why}) — claim NOT taken: the worktree and branch ` +
|
|
5626
|
+
'were removed again. The pushed claim ref is the record other machines read (#325, #550); fix the push ' +
|
|
5627
|
+
`(access, network, or a claim ref of that name another machine just created — \`git ls-remote ${pushRemote} ${claimRef}\`) and re-run.`);
|
|
5605
5628
|
}
|
|
5606
|
-
warn(`git push ${pushRemote} ${
|
|
5629
|
+
warn(`git push ${pushRemote} ${claimRef} failed (${why}) — worktree created, no claim ref on the remote`);
|
|
5607
5630
|
}
|
|
5608
5631
|
}
|
|
5609
5632
|
|
|
@@ -5625,14 +5648,14 @@ function cmdWorktreeNew(argv) {
|
|
|
5625
5648
|
}
|
|
5626
5649
|
|
|
5627
5650
|
// 3. allocate ports + record worktree + claims (atomic)
|
|
5628
|
-
// #325: if recording fails after the push above, take the pushed
|
|
5651
|
+
// #325: if recording fails after the push above, take the pushed claim ref back off the remote —
|
|
5629
5652
|
// otherwise it would stand there as a claim record nothing on any machine owns, refusing every
|
|
5630
5653
|
// later claim on these issues. (The local worktree is left as before this change.)
|
|
5631
5654
|
let alloc;
|
|
5632
5655
|
try {
|
|
5633
5656
|
alloc = allocWorktreeRecord();
|
|
5634
5657
|
} catch (e) {
|
|
5635
|
-
if (pushed) git.
|
|
5658
|
+
if (pushed) git.deleteClaimRef(repoAbs, pushRemote, branch);
|
|
5636
5659
|
throw e;
|
|
5637
5660
|
}
|
|
5638
5661
|
function allocWorktreeRecord() { return state.mutate((st) => {
|
|
@@ -5861,6 +5884,19 @@ function cmdWorktreeRm(argv) {
|
|
|
5861
5884
|
|
|
5862
5885
|
print(`✓ Removed worktree "${name}"`);
|
|
5863
5886
|
if (removal.action === 'rm-rf') print(' (directory was a husk from an earlier interrupted removal — cleaned up directly)');
|
|
5887
|
+
// #550: the claim ref `worktree new` pushed is this worktree's claim record on the remote — release
|
|
5888
|
+
// it with the claims, or it would stand there refusing every later claim on these issue numbers from
|
|
5889
|
+
// another machine. Best effort: an absent ref is fine (never pushed, a pre-#550 worktree, or already
|
|
5890
|
+
// gone), a failed delete only warns with the command, and nothing above is undone for it.
|
|
5891
|
+
if (wt.branch) {
|
|
5892
|
+
let claimRemoteName = null;
|
|
5893
|
+
try { claimRemoteName = git.claimRemote(repoAbs); } catch { claimRemoteName = null; }
|
|
5894
|
+
if (claimRemoteName) {
|
|
5895
|
+
const d = git.deleteClaimRef(repoAbs, claimRemoteName, wt.branch);
|
|
5896
|
+
if (d.ok && !d.absent) print(` deleted claim ref ${claimRemoteName} ${git.claimRef(wt.branch)}`);
|
|
5897
|
+
else if (!d.ok) warnDeferred(`could not delete claim ref ${claimRemoteName} ${git.claimRef(wt.branch)} (${String(d.stderr || '').split('\n')[0]}) — delete it by hand: git push ${claimRemoteName} --delete ${git.claimRef(wt.branch)}`);
|
|
5898
|
+
}
|
|
5899
|
+
}
|
|
5864
5900
|
// #114: this line used to report `removed.claims` — the LOCAL registry mutation, which cannot
|
|
5865
5901
|
// fail for a network reason and so always read as full success. Report what the tracker actually
|
|
5866
5902
|
// did instead, and name what it didn't.
|
package/tools/lib/git.js
CHANGED
|
@@ -297,21 +297,70 @@ function claimRemote(repo) {
|
|
|
297
297
|
}
|
|
298
298
|
|
|
299
299
|
/**
|
|
300
|
-
* Every branch head on `remoteName
|
|
301
|
-
* local cache)
|
|
302
|
-
* failed ask is NOT "no branches": it returns
|
|
303
|
-
* (fail closed) instead of reading an unreachable
|
|
304
|
-
* `{ ok: true, heads: [{ branch, sha }] }` otherwise, `sha` short
|
|
300
|
+
* Every branch head on `remoteName` — plus every claim ref (`refs/claims/<branch>`, #550) — asked
|
|
301
|
+
* of the remote directly (`ls-remote`, no fetch, no local cache): the claim record another machine
|
|
302
|
+
* can read (#325). Unlike `existingBranchRef`, a failed ask is NOT "no branches": it returns
|
|
303
|
+
* `{ ok: false, stderr }` so the caller can refuse (fail closed) instead of reading an unreachable
|
|
304
|
+
* remote as clear ground. `{ ok: true, heads: [{ branch, sha, claimRef? }] }` otherwise, `sha` short
|
|
305
|
+
* (7) — `parseRemoteHeads`.
|
|
305
306
|
*/
|
|
306
307
|
function remoteHeads(repo, remoteName) {
|
|
307
|
-
const r = git(['ls-remote', '
|
|
308
|
+
const r = git(['ls-remote', remoteName, 'refs/heads/*', `${CLAIM_REF_PREFIX}*`], repo, { timeoutMs: 60_000 });
|
|
308
309
|
if (!r.ok) return { ok: false, stderr: r.stderr || (r.timedOut ? 'ls-remote timed out' : `exit ${r.code}`) };
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
310
|
+
return { ok: true, heads: parseRemoteHeads(r.stdout) };
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* #550 — where `colab worktree new` records a claim at cut: `refs/claims/<branch>`, NOT the branch.
|
|
315
|
+
* A push to `refs/heads/<branch>` fires every CI `push` trigger, and at cut the branch is identical
|
|
316
|
+
* to trunk, so each claim re-ran the full suite on a commit trunk had already tested (measured: ~209
|
|
317
|
+
* of 230 duplicate runs in one org over 3 days, one sha run 8 times). GitHub fires `push` workflows
|
|
318
|
+
* for branches and tags only, so a ref outside both namespaces is a claim record every machine can
|
|
319
|
+
* still `ls-remote`, at zero CI cost (probed live 2026-10-07: a refs/claims push started no run).
|
|
320
|
+
* The branch itself reaches the remote at its first real push (code-wrap), where CI is wanted.
|
|
321
|
+
*/
|
|
322
|
+
const CLAIM_REF_PREFIX = 'refs/claims/';
|
|
323
|
+
function claimRef(branch) { return `${CLAIM_REF_PREFIX}${branch}`; }
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* `ls-remote` output → `[{ branch, sha, claimRef? }]`, short sha. A `refs/claims/<b>` entry reads as
|
|
327
|
+
* branch `<b>` with `claimRef: true`; when the same name is ALSO a real branch, only the branch row is
|
|
328
|
+
* kept (it is the stronger record — it carries commits). Pure, for tests.
|
|
329
|
+
*/
|
|
330
|
+
function parseRemoteHeads(stdout) {
|
|
331
|
+
const heads = new Map();
|
|
332
|
+
const claims = new Map();
|
|
333
|
+
for (const line of String(stdout || '').split('\n')) {
|
|
334
|
+
const m = line.match(/^([0-9a-f]{7,})\s+refs\/(heads|claims)\/(.+)$/);
|
|
335
|
+
if (!m) continue;
|
|
336
|
+
if (m[2] === 'heads') heads.set(m[3], { branch: m[3], sha: m[1].slice(0, 7) });
|
|
337
|
+
else claims.set(m[3], { branch: m[3], sha: m[1].slice(0, 7), claimRef: true });
|
|
313
338
|
}
|
|
314
|
-
|
|
339
|
+
for (const [b, c] of claims) if (!heads.has(b)) heads.set(b, c);
|
|
340
|
+
return [...heads.values()];
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Push the claim record for `branch` (#550): `<branch>:refs/claims/<branch>`, CREATE-ONLY
|
|
345
|
+
* (`--force-with-lease=<ref>:` with an empty expect), so two machines cutting one name still race on
|
|
346
|
+
* a real compare-and-swap and the loser is rejected. No `-u`: there is no remote branch to track yet.
|
|
347
|
+
*/
|
|
348
|
+
function pushClaimRef(repo, remote, branch) {
|
|
349
|
+
const ref = claimRef(branch);
|
|
350
|
+
return git(['push', remote, `--force-with-lease=${ref}:`, `refs/heads/${branch}:${ref}`], repo, { timeoutMs: 120_000 });
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* Delete the claim record for `branch` from `remote` (#550). Idempotent: an absent ref is success
|
|
355
|
+
* (nothing to release), so teardown never fails on a claim that was never pushed or already gone.
|
|
356
|
+
*/
|
|
357
|
+
function deleteClaimRef(repo, remote, branch) {
|
|
358
|
+
const ref = claimRef(branch);
|
|
359
|
+
const ls = git(['ls-remote', remote, ref], repo, { timeoutMs: 60_000 });
|
|
360
|
+
if (!ls.ok) return { ok: false, stderr: ls.stderr || `exit ${ls.code}` };
|
|
361
|
+
if (!String(ls.stdout || '').trim()) return { ok: true, absent: true };
|
|
362
|
+
const r = git(['push', remote, '--delete', ref], repo, { timeoutMs: 120_000 });
|
|
363
|
+
return { ok: r.ok, stderr: r.stderr };
|
|
315
364
|
}
|
|
316
365
|
|
|
317
366
|
/** List worktree paths registered in a repo (porcelain). */
|
|
@@ -1329,7 +1378,7 @@ module.exports = {
|
|
|
1329
1378
|
ghCommitCheckRuns, ghCheckRunAnnotations,
|
|
1330
1379
|
run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
|
|
1331
1380
|
detectTrunk, branchExists, branchRefs, existingBranchRef,
|
|
1332
|
-
claimRemote, remoteHeads,
|
|
1381
|
+
claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
|
|
1333
1382
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1334
1383
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1335
1384
|
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
@@ -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
|
}
|