@futurelastic/colab-handbook 1.18.0-rc.12 → 1.18.0-rc.13
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 +48 -5
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -3950,6 +3950,8 @@ change. Nothing else can produce a grant — no --force on ship, no project.yml
|
|
|
3950
3950
|
from an issue's content, age or park count. A human act on the issue is the whole answer.
|
|
3951
3951
|
|
|
3952
3952
|
colab migration-grant <N> --branch <branch> grant #N an exemption, bound to <branch>
|
|
3953
|
+
colab migration-grant <N> --branch vX.Y.Z on a release tracking issue: bound to that version
|
|
3954
|
+
(#677 — the command a release hand-off prints)
|
|
3953
3955
|
colab migration-grant <N> --revoke revoke #N's grant (idempotent — safe if none exists)
|
|
3954
3956
|
colab migration-grant --list [--json] list every issue with a live grant right now
|
|
3955
3957
|
|
|
@@ -3975,6 +3977,13 @@ Revoking removes the label FIRST (the gate is restored the same minute) and post
|
|
|
3975
3977
|
grantor — any revoke comment cancels every live grant on that issue, because a safety gate should
|
|
3976
3978
|
fail toward "closed" if either half only partially lands.
|
|
3977
3979
|
|
|
3980
|
+
A RELEASE VERSION (#677). --branch must name a ref (a local branch or origin's copy) — with one
|
|
3981
|
+
exception: a human grant naming a final version \`vX.Y.Z\` that is not a ref, on the issue whose body
|
|
3982
|
+
starts with that version's tracking marker (\`<!-- colab:release version=vX.Y.Z -->\`). That is the
|
|
3983
|
+
grant a release hand-off asks for (\`colab release cut --auto\` on deploy-tag-fast, and a deploy-tag
|
|
3984
|
+
candidate): the version becomes a tag only after the grant, and the release gate reads the grant
|
|
3985
|
+
against the version. Any other version — a typo, or one #N does not track — is refused, nothing posted.
|
|
3986
|
+
|
|
3978
3987
|
There is deliberately no local-only fallback: without a usable \`gh\`, every subcommand here REFUSES
|
|
3979
3988
|
rather than write (or read) something invisible to the machine \`ship\` might later run on.
|
|
3980
3989
|
|
|
@@ -4064,7 +4073,15 @@ function cmdMigrationGrant(argv) {
|
|
|
4064
4073
|
if (!opts.revoke && !opts.branch) {
|
|
4065
4074
|
throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
|
|
4066
4075
|
}
|
|
4067
|
-
|
|
4076
|
+
// #677: a release version is the one binding name that is not a ref when it is granted — on route
|
|
4077
|
+
// deploy-tag-fast (and a deploy-tag candidate) the grant is what lets `vX.Y.Z` be tagged at all,
|
|
4078
|
+
// and the release gate compares the grant against the computed version, never a ref. So a human
|
|
4079
|
+
// grant naming a canonical final version is deferred here to cmdMigrationGrantCreate, which accepts
|
|
4080
|
+
// it only when #N's tracking marker names exactly that version: a typo is still refused, just one
|
|
4081
|
+
// step later (it needs the tracker). Any other name — and a reviewer grant, which binds a pushed
|
|
4082
|
+
// HEAD — keeps the ref check below, unchanged.
|
|
4083
|
+
if (!opts.revoke) opts.versionBinding = migrationGrantVersionBinding(repoAbs, opts);
|
|
4084
|
+
if (!opts.revoke && !opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
|
|
4068
4085
|
throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
|
|
4069
4086
|
}
|
|
4070
4087
|
// #397: the role, and for a reviewer grant its whole record — all answerable locally, so all
|
|
@@ -4085,6 +4102,19 @@ function cmdMigrationGrant(argv) {
|
|
|
4085
4102
|
return opts.revoke ? cmdMigrationGrantRevoke(repoAbs, num) : cmdMigrationGrantCreate(repoAbs, num, opts);
|
|
4086
4103
|
}
|
|
4087
4104
|
|
|
4105
|
+
/**
|
|
4106
|
+
* #677: true when this grant binds a release VERSION rather than a branch — a human grant whose
|
|
4107
|
+
* --branch is a canonical final version (`vX.Y.Z`, never an `-rc.N`) that resolves to no ref here.
|
|
4108
|
+
* Local only, so it runs before the gh gate; cmdMigrationGrantCreate then holds it to the issue's
|
|
4109
|
+
* tracking marker (`<!-- colab:release version=vX.Y.Z -->`). A ref of that name wins: the grant is
|
|
4110
|
+
* an ordinary branch grant and nothing about it changes.
|
|
4111
|
+
*/
|
|
4112
|
+
function migrationGrantVersionBinding(repoAbs, opts) {
|
|
4113
|
+
if (opts.role !== undefined && String(opts.role) !== 'human') return false;
|
|
4114
|
+
if (!releaseCut.parseVersion(opts.branch)) return false;
|
|
4115
|
+
return !git.branchExists(repoAbs, opts.branch);
|
|
4116
|
+
}
|
|
4117
|
+
|
|
4088
4118
|
/**
|
|
4089
4119
|
* #397: resolve the grant's role and, for a reviewer grant, build and check its review record.
|
|
4090
4120
|
* Returns null for a human grant (the unchanged path). Throws UserError on anything a reviewer
|
|
@@ -4205,15 +4235,23 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
4205
4235
|
if (!opts.branch) {
|
|
4206
4236
|
throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
|
|
4207
4237
|
}
|
|
4208
|
-
if (!git.branchExists(repoAbs, opts.branch)) {
|
|
4238
|
+
if (!opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
|
|
4209
4239
|
throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
|
|
4210
4240
|
}
|
|
4211
4241
|
|
|
4212
|
-
const info = git.ghIssueView(repoAbs, num, ['state', 'labels']);
|
|
4242
|
+
const info = git.ghIssueView(repoAbs, num, opts.versionBinding ? ['state', 'labels', 'body'] : ['state', 'labels']);
|
|
4213
4243
|
if (!info) throw new UserError(`could not read #${num} from the tracker — refusing to write a grant blind`);
|
|
4214
4244
|
if (info.state !== 'OPEN') {
|
|
4215
4245
|
throw new UserError(`#${num} is ${info.state} — a grant expires the instant its issue closes, so granting a closed one would do nothing (CONVENTIONS.md §5, Migration exemption)`);
|
|
4216
4246
|
}
|
|
4247
|
+
// #677: a version-bound grant stands on the tracking marker in place of a ref — the name must be
|
|
4248
|
+
// exactly the version #N tracks, so a typo still binds nothing.
|
|
4249
|
+
if (opts.versionBinding) {
|
|
4250
|
+
const tracked = releaseFinalize.parseReleaseMarker(info.body);
|
|
4251
|
+
if (tracked !== opts.branch) {
|
|
4252
|
+
throw new UserError(`"${opts.branch}" is not a ref, and #${num} ${tracked ? `tracks ${tracked}, not ${opts.branch}` : 'carries no release tracking marker (<!-- colab:release version=vX.Y.Z -->)'} — a version is granted only on its own tracking issue; nothing was posted. Re-run with the version #${num} tracks, or the branch the migration is on: COLAB_HUMAN=1 colab migration-grant ${num} --branch ${tracked || '<branch>'}`);
|
|
4253
|
+
}
|
|
4254
|
+
}
|
|
4217
4255
|
|
|
4218
4256
|
const present = git.ghListLabels(repoAbs);
|
|
4219
4257
|
if (present && !present.includes(labels.MIGRATION_GRANT_LABEL)) {
|
|
@@ -4253,8 +4291,13 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
4253
4291
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
4254
4292
|
return 0;
|
|
4255
4293
|
}
|
|
4256
|
-
|
|
4257
|
-
|
|
4294
|
+
if (opts.versionBinding) {
|
|
4295
|
+
print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for release ${opts.branch}.`);
|
|
4296
|
+
print(` This covers ONLY that version's final, and expires the moment #${num} closes. The next green release run tags it.`);
|
|
4297
|
+
} else {
|
|
4298
|
+
print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for branch "${opts.branch}".`);
|
|
4299
|
+
print(` This covers ONLY this branch, and expires the moment #${num} closes.`);
|
|
4300
|
+
}
|
|
4258
4301
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
4259
4302
|
// Deliberately no pushEvent — see HELP_SHIP's JSON note: no receiver-agreed kind exists for
|
|
4260
4303
|
// this yet, and both markers are already visible on the tracker from any machine.
|