@futurelastic/colab-handbook 1.19.1-rc.1 → 1.19.1-rc.2
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 -3
- package/tools/lib/adopt.js +2 -1
- package/tools/lib/codec/labels.d.ts +9 -0
- package/tools/lib/codec/labels.js +57 -0
- package/tools/lib/codec/samples.json +8 -0
- package/tools/lib/disposition.js +16 -14
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -8022,7 +8022,7 @@ const DELIVERY_LABEL_COUNT = labels.conventionLabelNames()
|
|
|
8022
8022
|
const DEFERRED_LABEL_COUNT = labels.conventionLabelNames()
|
|
8023
8023
|
.filter((n) => n.startsWith(labels.DEFERRED_LABEL_PREFIX)).length;
|
|
8024
8024
|
|
|
8025
|
-
const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--repo P]
|
|
8025
|
+
const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--relabel-deprecated] [--prune-deprecated] [--repo P]
|
|
8026
8026
|
|
|
8027
8027
|
Create every convention label this repo is missing — CONVENTIONS.md §9 step 3, the ${labels.conventionLabelNames().length}-name set
|
|
8028
8028
|
(${NON_DELIVERY_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}, the ${DELIVERY_LABEL_COUNT} \`delivery:*\` values, and the ${DEFERRED_LABEL_COUNT} \`deferred:*\` values),
|
|
@@ -8041,6 +8041,13 @@ used to be typed out by hand (#206).
|
|
|
8041
8041
|
${labels.MINIMAL_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}. For a repo the fleet does not own
|
|
8042
8042
|
(CONVENTIONS.md §9, "Working in a repo you don't own") — every other
|
|
8043
8043
|
label is opt-in by use there, not provisioned on someone else's tracker
|
|
8044
|
+
--relabel-deprecated move every OPEN issue carrying a deprecated label (${codec.DEPRECATED_LABELS.map((d) => `\`${d.name}\``).join(', ')})
|
|
8045
|
+
onto its replacement — add the new label, remove the old (#683). Closed
|
|
8046
|
+
issues keep the old label as history. Without this flag they are only reported
|
|
8047
|
+
--prune-deprecated delete a deprecated label from the tracker — only once its window has ended
|
|
8048
|
+
(${codec.HUMAN_WAIT_ALIAS_UNTIL}) AND a non-search read confirms no open issue still
|
|
8049
|
+
carries it. Deleting strips the label from closed issues too, so it is never
|
|
8050
|
+
implied by --relabel-deprecated
|
|
8044
8051
|
--repo <path> repo root (default: git root of cwd)
|
|
8045
8052
|
|
|
8046
8053
|
Idempotent: a label already present is never re-created and reported under "already there" —
|
|
@@ -8062,9 +8069,15 @@ rejects) — each failure is reported by name, not just a bare non-zero.
|
|
|
8062
8069
|
function cmdLabels(argv) {
|
|
8063
8070
|
const opts = parseArgs(argv, {
|
|
8064
8071
|
values: { '--repo': 'repo', '--keep': 'keep' },
|
|
8065
|
-
flags: {
|
|
8072
|
+
flags: {
|
|
8073
|
+
'--ensure': 'ensure', '--refresh-descriptions': 'refresh', '--minimal': 'minimal',
|
|
8074
|
+
'--relabel-deprecated': 'relabel', '--prune-deprecated': 'prune', '-h': 'help', '--help': 'help',
|
|
8075
|
+
},
|
|
8066
8076
|
});
|
|
8067
8077
|
if (opts.help || !opts.ensure) return print(HELP_LABELS);
|
|
8078
|
+
if (opts.minimal && (opts.relabel || opts.prune)) {
|
|
8079
|
+
throw new UserError('--relabel-deprecated / --prune-deprecated move issues onto a label --minimal does not provision — drop --minimal');
|
|
8080
|
+
}
|
|
8068
8081
|
if (opts.keep !== undefined && !opts.refresh) {
|
|
8069
8082
|
throw new UserError('--keep only means something with --refresh-descriptions — without it no description is rewritten, so there is nothing to keep');
|
|
8070
8083
|
}
|
|
@@ -8135,6 +8148,51 @@ function cmdLabels(argv) {
|
|
|
8135
8148
|
print('(CONVENTIONS.md §8, Upstream; skills/handbook-sync/SKILL.md §7).');
|
|
8136
8149
|
}
|
|
8137
8150
|
}
|
|
8151
|
+
// #683: deprecated aliases (codec.DEPRECATED_LABELS). Only a label the tracker actually has is
|
|
8152
|
+
// read, so a repo that never carried an old spelling costs no extra call. --minimal skips this:
|
|
8153
|
+
// the replacement is outside the subset it provisions.
|
|
8154
|
+
if (!opts.minimal) {
|
|
8155
|
+
const have = new Set(present.map((l) => l.name));
|
|
8156
|
+
const target = (name) => have.has(name) || created.includes(name);
|
|
8157
|
+
const day = today();
|
|
8158
|
+
for (const d of codec.DEPRECATED_LABELS) {
|
|
8159
|
+
if (!have.has(d.name)) continue;
|
|
8160
|
+
const v = codec.deprecatedLabelDecision(d, { today: day, open: git.ghOpenIssueNumbersByLabel(repoAbs, d.name) });
|
|
8161
|
+
if (v.action === 'move') {
|
|
8162
|
+
const list = v.open.map((n) => `#${n}`).join(', ');
|
|
8163
|
+
if (!opts.relabel) {
|
|
8164
|
+
print(`Deprecated label in use: ${d.name} on ${list} — replaced by ${d.replacedBy} (alias window ends ${d.until}).`);
|
|
8165
|
+
print(' Move them: colab labels --ensure --relabel-deprecated');
|
|
8166
|
+
continue;
|
|
8167
|
+
}
|
|
8168
|
+
if (!target(d.replacedBy)) {
|
|
8169
|
+
failed.push({ name: d.name, error: `${d.replacedBy} is not on the tracker, so ${list} cannot move onto it` });
|
|
8170
|
+
continue;
|
|
8171
|
+
}
|
|
8172
|
+
const moved = [];
|
|
8173
|
+
for (const n of v.open) {
|
|
8174
|
+
const r = git.ghIssueEdit(repoAbs, n, ['--add-label', d.replacedBy, '--remove-label', d.name]);
|
|
8175
|
+
if (r.ok) moved.push(`#${n}`);
|
|
8176
|
+
else failed.push({ name: `${d.name} on #${n}`, error: (r.stderr || '').trim() || 'gh issue edit failed' });
|
|
8177
|
+
}
|
|
8178
|
+
if (moved.length) print(`Relabelled ${d.name} → ${d.replacedBy}: ${moved.join(', ')}`);
|
|
8179
|
+
} else if (v.action === 'delete') {
|
|
8180
|
+
if (!opts.prune) {
|
|
8181
|
+
print(`Deprecated label ${d.name}: no open issue carries it and its window ended ${d.until} — delete it: colab labels --ensure --prune-deprecated`);
|
|
8182
|
+
continue;
|
|
8183
|
+
}
|
|
8184
|
+
const r = git.ghLabelDelete(repoAbs, d.name);
|
|
8185
|
+
if (r.ok) print(`Deleted deprecated label: ${d.name}`);
|
|
8186
|
+
else failed.push({ name: d.name, error: (r.stderr || '').trim() || 'gh label delete failed' });
|
|
8187
|
+
} else if (v.reason === 'unread') {
|
|
8188
|
+
const why = `could not read the open issues carrying ${d.name} — left as it is`;
|
|
8189
|
+
if (opts.relabel || opts.prune) failed.push({ name: d.name, error: why });
|
|
8190
|
+
else print(`Deprecated label ${d.name}: ${why}`);
|
|
8191
|
+
} else {
|
|
8192
|
+
print(`Deprecated label ${d.name}: no open issue carries it; kept until its window ends ${d.until}${opts.prune ? ' (--prune-deprecated deletes it only after that)' : ''}.`);
|
|
8193
|
+
}
|
|
8194
|
+
}
|
|
8195
|
+
}
|
|
8138
8196
|
if (failed.length) {
|
|
8139
8197
|
print('Failed:');
|
|
8140
8198
|
for (const f of failed) print(` ${f.name} — ${f.error}`);
|
|
@@ -17932,7 +17990,9 @@ Commands:
|
|
|
17932
17990
|
labels --ensure [--repo P] create every missing convention label (§9 step 3, #206) —
|
|
17933
17991
|
idempotent, reports created vs already-there, and names every
|
|
17934
17992
|
label whose description drifted (#364); --refresh-descriptions
|
|
17935
|
-
[--keep a,b] rewrites those to the handbook's text
|
|
17993
|
+
[--keep a,b] rewrites those to the handbook's text;
|
|
17994
|
+
--relabel-deprecated moves open issues off a deprecated
|
|
17995
|
+
label, --prune-deprecated deletes it after its window (#683)
|
|
17936
17996
|
config [show|add-repo P|rm-repo P|set K V]
|
|
17937
17997
|
|
|
17938
17998
|
State is machine-local at ~/.colab/ (override with COLAB_HOME). Run any command with
|
package/tools/lib/adopt.js
CHANGED
|
@@ -34,6 +34,7 @@ const yaml = require('./yaml.js');
|
|
|
34
34
|
const { consumerEvidence, describeEvidence } = require('./consumer-evidence.js');
|
|
35
35
|
const { evaluateExposure } = require('./exposure-shape.js');
|
|
36
36
|
const { UserError } = require('./util.js');
|
|
37
|
+
const labels = require('./codec/labels.js');
|
|
37
38
|
|
|
38
39
|
const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
|
|
39
40
|
|
|
@@ -397,7 +398,7 @@ function remainingSteps(ctx = {}) {
|
|
|
397
398
|
const steps = [];
|
|
398
399
|
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
399
400
|
steps.push(
|
|
400
|
-
{ n: 3, text:
|
|
401
|
+
{ n: 3, text: `Create the full label set (${labels.conventionLabelNames().length} names) — \`colab labels --ensure\`, CONVENTIONS.md §9 step 3 (#206)` },
|
|
401
402
|
{ n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
|
|
402
403
|
);
|
|
403
404
|
if (ctx.fork) {
|
|
@@ -22,6 +22,15 @@ export const CONVENTION_LABELS: ConventionLabel[];
|
|
|
22
22
|
export function conventionLabelNames(): string[];
|
|
23
23
|
export function missingConventionLabels(present: LabelLike[] | null | undefined): string[];
|
|
24
24
|
export function staleConventionDescriptions(present: LabelLike[] | null | undefined): { name: string; have: string; want: string }[];
|
|
25
|
+
/** #683: a deprecated spelling, the label replacing it, and the last day (YYYY-MM-DD) of its window. */
|
|
26
|
+
export interface DeprecatedLabel { name: string; replacedBy: string; until: string; }
|
|
27
|
+
export const HUMAN_WAIT_ALIAS_UNTIL: string;
|
|
28
|
+
export const DEPRECATED_LABELS: ReadonlyArray<DeprecatedLabel>;
|
|
29
|
+
export function deprecatedLabel(name: LabelLike): DeprecatedLabel | null;
|
|
30
|
+
export function deprecatedLabelDecision(entry: DeprecatedLabel, facts?: { today?: string; open?: number[] | null }):
|
|
31
|
+
| { action: 'move'; reason: 'open'; open: number[] }
|
|
32
|
+
| { action: 'delete'; reason: 'spent'; open: [] }
|
|
33
|
+
| { action: 'keep'; reason: 'unread' | 'window' | 'bad-date'; open: [] };
|
|
25
34
|
export const MINIMAL_LABEL_NAMES: string[];
|
|
26
35
|
export function minimalConventionLabels(): ConventionLabel[];
|
|
27
36
|
|
|
@@ -213,6 +213,15 @@
|
|
|
213
213
|
* malignant-absence reason above: the moment a human wants to veto is a test period that is
|
|
214
214
|
* already counting down, and a label the repo never created cannot be applied in that moment —
|
|
215
215
|
* the veto would silently not exist. Only a human removes it; no command in this repo does.
|
|
216
|
+
*
|
|
217
|
+
* `blocked:needs-human` joined the set in #683: the park label for "waits until a person decides
|
|
218
|
+
* or acts" — the label form of the `needs-human` disposition (tools/lib/disposition.js). Before
|
|
219
|
+
* it the wait had two role-named spellings (DEPRECATED_LABELS below), neither provisioned, so
|
|
220
|
+
* adopters hand-created them with different colours and descriptions, and on an install where
|
|
221
|
+
* the person who lifts the park is not the install's owner the name pointed at someone else.
|
|
222
|
+
* Provisioned for the malignant-absence reason above: a park a session wants to record must be
|
|
223
|
+
* appliable at that moment. Not in MINIMAL_LABEL_NAMES — a session's start → wrap → ship path
|
|
224
|
+
* does not write it.
|
|
216
225
|
*/
|
|
217
226
|
|
|
218
227
|
const CONVENTION_LABELS = [
|
|
@@ -239,8 +248,55 @@ const CONVENTION_LABELS = [
|
|
|
239
248
|
{ name: 'deferred:measurement', color: '7C6F57', description: 'Parked until a metric crosses a threshold — name the metric and the threshold on the issue' },
|
|
240
249
|
{ name: 'deferred:external-party', color: '6E5494', description: 'Parked until someone outside this repo acts — name who, and pair with review-by:<date>' },
|
|
241
250
|
{ name: 'release-hold', color: 'E11D21', description: 'Human veto on a release tracking issue: its candidate is not finalized while this is present' },
|
|
251
|
+
{ name: 'blocked:needs-human', color: 'D93F0B', description: 'Parked until a person decides or acts — a decision or an act only a person can give' },
|
|
242
252
|
];
|
|
243
253
|
|
|
254
|
+
// The label alias table (#683) — deprecated spellings of a convention label, each with the label
|
|
255
|
+
// that replaces it and the last day of its migration window (YYYY-MM-DD). Read, never written:
|
|
256
|
+
// nothing in this repo applies one. `colab labels --ensure` reports open issues still carrying
|
|
257
|
+
// one, `--relabel-deprecated` moves them, and `--prune-deprecated` deletes the old label once the
|
|
258
|
+
// window is over (deprecatedLabelDecision below). The window is a DATE, not a release count:
|
|
259
|
+
// minor releases here ship days apart, so a release-counted window would close before most
|
|
260
|
+
// adopters had synced once. Dropping an entry is a separate change, made after its date.
|
|
261
|
+
const HUMAN_WAIT_ALIAS_UNTIL = '2027-01-06';
|
|
262
|
+
const DEPRECATED_LABELS = Object.freeze([
|
|
263
|
+
Object.freeze({ name: 'blocked:needs-owner', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
|
|
264
|
+
Object.freeze({ name: 'blocked:needs-boss', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
|
|
265
|
+
]);
|
|
266
|
+
|
|
267
|
+
/** The DEPRECATED_LABELS entry for `name`, or null. Tolerant of a label object or a bare string. */
|
|
268
|
+
function deprecatedLabel(name) {
|
|
269
|
+
const s = name && typeof name === 'object' ? name.name : name;
|
|
270
|
+
return DEPRECATED_LABELS.find((d) => d.name === s) || null;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* What to do with one deprecated label on one tracker — pure, so the clock and the tracker read
|
|
275
|
+
* are both inputs (#683). `entry` is a DEPRECATED_LABELS row, `today` a YYYY-MM-DD string, `open`
|
|
276
|
+
* the open issue numbers carrying the label from a NON-search read (null = could not read).
|
|
277
|
+
*
|
|
278
|
+
* Returns { action, reason, open }:
|
|
279
|
+
* - `move` — open issues carry it: relabel them onto `entry.replacedBy`. Moving is always
|
|
280
|
+
* allowed, inside the window or after it.
|
|
281
|
+
* - `delete` — the window is over (today is after `until`) AND the read confirms no open issue
|
|
282
|
+
* carries it: the label object may be deleted.
|
|
283
|
+
* - `keep` — anything else: `unread` (the read failed — never read as "none open"), `window`
|
|
284
|
+
* (still inside the window; aliases are guaranteed until `until`), `bad-date`.
|
|
285
|
+
*
|
|
286
|
+
* Deleting a label object strips it from closed issues too and cannot be undone from the tracker,
|
|
287
|
+
* so every unclear input keeps — the same posture as group-labels.js's spent-label teardown.
|
|
288
|
+
*/
|
|
289
|
+
function deprecatedLabelDecision(entry, { today, open } = {}) {
|
|
290
|
+
if (!Array.isArray(open)) return { action: 'keep', reason: 'unread', open: [] };
|
|
291
|
+
if (open.length) return { action: 'move', reason: 'open', open: [...open] };
|
|
292
|
+
const day = /^\d{4}-\d{2}-\d{2}$/;
|
|
293
|
+
if (!entry || !day.test(String(entry.until)) || !day.test(String(today))) {
|
|
294
|
+
return { action: 'keep', reason: 'bad-date', open: [] };
|
|
295
|
+
}
|
|
296
|
+
if (today <= entry.until) return { action: 'keep', reason: 'window', open: [] };
|
|
297
|
+
return { action: 'delete', reason: 'spent', open: [] };
|
|
298
|
+
}
|
|
299
|
+
|
|
244
300
|
// The DELIVERY label prefix (CONVENTIONS.md §5, Delivery type). Six fixed values, unlike
|
|
245
301
|
// `group:<key>` — provisioned up front in CONVENTION_LABELS above, not created on demand.
|
|
246
302
|
const DELIVERY_LABEL_PREFIX = 'delivery:';
|
|
@@ -707,6 +763,7 @@ function encodeLabel(label) {
|
|
|
707
763
|
|
|
708
764
|
module.exports = {
|
|
709
765
|
CONVENTION_LABELS, conventionLabelNames, missingConventionLabels, staleConventionDescriptions,
|
|
766
|
+
HUMAN_WAIT_ALIAS_UNTIL, DEPRECATED_LABELS, deprecatedLabel, deprecatedLabelDecision,
|
|
710
767
|
MINIMAL_LABEL_NAMES, minimalConventionLabels,
|
|
711
768
|
READINESS_LABEL, readinessLabelArgs, readinessMissingLabelHint, readinessMarkedMessage,
|
|
712
769
|
TRACKING_LABEL,
|
package/tools/lib/disposition.js
CHANGED
|
@@ -69,19 +69,21 @@ const HUMAN = 'human';
|
|
|
69
69
|
* GitHub's close reason takes. Frozen and closed: a kind outside this list is not a disposition
|
|
70
70
|
* with an unknown authority, it is not a disposition.
|
|
71
71
|
*/
|
|
72
|
-
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-
|
|
72
|
+
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-human', 'not planned', 'leave']);
|
|
73
73
|
|
|
74
74
|
/**
|
|
75
|
-
* #609 — names this module still READS but never writes.
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
75
|
+
* #609, #683 — the alias table: names this module still READS but never writes. The person-wait
|
|
76
|
+
* kind is `needs-human` — it names the wait, not a role, so it reads right on any install,
|
|
77
|
+
* whoever lifts the park. Both older names are deprecated aliases of it. During the switch a
|
|
78
|
+
* reader must accept them, or an issue marked under an old name reads as unrecognised — "not
|
|
79
|
+
* cleared" — to a tool that only knows the new one. Each alias classifies exactly like the kind
|
|
80
|
+
* it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer may
|
|
81
|
+
* emit, and `formatMarker` refuses an alias. The window the aliases are guaranteed for is the
|
|
82
|
+
* label alias table's date (`HUMAN_WAIT_ALIAS_UNTIL`, tools/lib/codec/labels.js). Reading does
|
|
83
|
+
* not stop at that date; dropping an entry is a separate change, made after it.
|
|
82
84
|
*/
|
|
83
|
-
const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-
|
|
84
|
-
const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-
|
|
85
|
+
const LEGACY_KINDS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
|
|
86
|
+
const LEGACY_TOKENS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
|
|
85
87
|
|
|
86
88
|
/**
|
|
87
89
|
* The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
|
|
@@ -94,13 +96,13 @@ const TOKEN_BY_KIND = Object.freeze({
|
|
|
94
96
|
split: 'split',
|
|
95
97
|
'routed-out': 'routed-out',
|
|
96
98
|
hold: 'hold',
|
|
97
|
-
'needs-
|
|
99
|
+
'needs-human': 'needs-human',
|
|
98
100
|
'not planned': 'not-planned',
|
|
99
101
|
leave: 'leave',
|
|
100
102
|
});
|
|
101
103
|
const KIND_BY_TOKEN = Object.freeze({
|
|
102
104
|
...Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind])),
|
|
103
|
-
...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609)
|
|
105
|
+
...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609, #683)
|
|
104
106
|
});
|
|
105
107
|
const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
|
|
106
108
|
|
|
@@ -348,11 +350,11 @@ function classify(facts) {
|
|
|
348
350
|
: verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
|
|
349
351
|
}
|
|
350
352
|
|
|
351
|
-
case 'needs-
|
|
353
|
+
case 'needs-human':
|
|
352
354
|
// Record-first: the pass writes the question down with the apply lever pre-filled and moves
|
|
353
355
|
// on. It does not stop and wait, and it never applies this itself.
|
|
354
356
|
return verdict(kind, HUMAN, true,
|
|
355
|
-
'never applied by an agent — the agent records the question,
|
|
357
|
+
'never applied by an agent — the agent records the question, a person answers, the issue returns to intake', []);
|
|
356
358
|
|
|
357
359
|
case 'not planned': {
|
|
358
360
|
const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};
|