@futurelastic/colab-handbook 1.12.0-rc.55 → 1.12.0-rc.56
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/lib/adopt.js +83 -1
package/package.json
CHANGED
package/tools/lib/adopt.js
CHANGED
|
@@ -308,7 +308,80 @@ function listShort(items) {
|
|
|
308
308
|
* step 5 becomes the append-only block instead of the thin-shell conversion
|
|
309
309
|
* (CONVENTIONS.md §9, *A fork of an upstream*)
|
|
310
310
|
* upstreamAgentFiles — on a fork, the upstream's own agent workflow, named for the precedence line
|
|
311
|
+
* releaseRung — `releaseRungSteps()`'s result (#492): extra step-6 lines on exposure: released
|
|
311
312
|
*/
|
|
313
|
+
const releasePolicy = require('./release-policy.js');
|
|
314
|
+
|
|
315
|
+
const FINAL_TAG = /^v\d+\.\d+\.\d+$/;
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* #492 — on `exposure: released`, step 6 is not only CI: the release rung (CONVENTIONS.md §6) has
|
|
319
|
+
* to be wired at adoption too, or the repo never cuts a candidate until someone notices. Measured:
|
|
320
|
+
* six adopters in one fleet sweep with no `release:` block and no release workflow, several more
|
|
321
|
+
* with the workflow but no first final (`release cut` refuses with no final to bump from).
|
|
322
|
+
*
|
|
323
|
+
* Pure: reads the descriptor and what `io` already exposes. Returns step-6 entries (possibly
|
|
324
|
+
* none). Never decides a route on a human's behalf beyond §6's own derivation — the no-production
|
|
325
|
+
* row's choice is PROPOSED (public room -> public-tool, else rapid-app), and the text says so.
|
|
326
|
+
*
|
|
327
|
+
* `ctx`: { cfg, workflowTexts: { [file]: text }, tags: string[]|null, stackFiles: string[] }
|
|
328
|
+
*/
|
|
329
|
+
function releaseRungSteps(ctx = {}) {
|
|
330
|
+
const cfg = ctx.cfg || {};
|
|
331
|
+
const def = releasePolicy.deriveDefault(cfg);
|
|
332
|
+
const exposure = axisAuthority.axisOfRecord(cfg).exposure;
|
|
333
|
+
if (exposure !== 'released') return [];
|
|
334
|
+
const steps = [];
|
|
335
|
+
const block = cfg.release && typeof cfg.release === 'object' ? cfg.release : null;
|
|
336
|
+
|
|
337
|
+
// 6a — the release: block.
|
|
338
|
+
if (block && block.route) {
|
|
339
|
+
steps.push({ n: 6, text: `Release rung: \`release.route: ${block.route}\` declared — keep it; confirm \`version-source\` (default \`tag\` where the machine cuts the tag, #484), CONVENTIONS.md §6 *Release routes*` });
|
|
340
|
+
} else if (def.row === 'released-tag' || def.row === 'released-manual') {
|
|
341
|
+
steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: deploy-tag\` and \`version-source: tag\` (block style — the descriptor reader parses no \`{ }\` flow map) — the tag deploys production (deploy: ${cfg.deploy}), so candidates are automatic and every final is a human click (CONVENTIONS.md §6 *Release routes*, #492)` });
|
|
342
|
+
} else if (def.row === 'released-no-production') {
|
|
343
|
+
const proposed = cfg.room === 'public' ? 'public-tool' : 'rapid-app';
|
|
344
|
+
steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: ${proposed}\` and \`version-source: tag\` (block style) — PROPOSED from room: ${cfg.room || 'undeclared'} (public CLI/handbook adopters install → public-tool; an app or tool with few installers → rapid-app; a library its consumers pin → library-fast) — confirm with the human, CONVENTIONS.md §6 *Release routes* (#492)` });
|
|
345
|
+
} else {
|
|
346
|
+
steps.push({ n: 6, text: 'Release rung: exposure: released but production/deploy match no §6 row — no route derives, a human tags; fix `deploy:`/`production:` before wiring a release workflow (CONVENTIONS.md §6, #492)' });
|
|
347
|
+
return steps;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
// 6b — the release workflow.
|
|
351
|
+
const texts = ctx.workflowTexts || {};
|
|
352
|
+
const releaseWf = Object.keys(texts).find((f) => /colab release cut/.test(texts[f] || ''));
|
|
353
|
+
if (releaseWf) {
|
|
354
|
+
steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the self-hosted label on a private repo` });
|
|
355
|
+
} else {
|
|
356
|
+
steps.push({ n: 6, text: 'Copy the release workflow — `colab template release-auto`, then walk its `# EDIT:` points: `HANDBOOK_REF` (a channel or tag the handbook carries, #480), the test-suite workflow `name:`, and on a PRIVATE repo the self-hosted runner label from ci.yml on every job except `npm` (#492)' });
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
// 6c — a deploy template by stack, only where the tag deploys.
|
|
360
|
+
if (def.row === 'released-tag' || def.row === 'released-manual') {
|
|
361
|
+
const files = new Set(ctx.stackFiles || []);
|
|
362
|
+
const deployWf = Object.keys(texts).find((f) => /^deploy/.test(f));
|
|
363
|
+
const php = files.has('composer.json');
|
|
364
|
+
const container = ['Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml'].some((f) => files.has(f));
|
|
365
|
+
const tpl = php ? 'deploy-xserver' : container ? 'deploy-container' : null;
|
|
366
|
+
if (deployWf) {
|
|
367
|
+
steps.push({ n: 6, text: `Deploy workflow present (.github/workflows/${deployWf}) — nothing to copy` });
|
|
368
|
+
} else if (tpl) {
|
|
369
|
+
steps.push({ n: 6, text: `Copy the deploy template for this stack — \`colab template ${tpl}\` (${php ? 'PHP: composer.json' : 'container: a Dockerfile/compose file'}) — and keep it DISARMED: leave only its \`workflow_dispatch\` trigger until the operator has set its secrets and arms the \`push: tags\` trigger (#492)` });
|
|
370
|
+
} else {
|
|
371
|
+
steps.push({ n: 6, text: 'No deploy template matches this stack (none for it under templates/) — the deploy stays the runbook\'s, by hand (#492)' });
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
// 6d — the first final.
|
|
376
|
+
const tags = ctx.tags;
|
|
377
|
+
if (tags === null || tags === undefined) {
|
|
378
|
+
steps.push({ n: 6, text: 'First final: tags could not be read — check for a `vX.Y.Z` final; `colab release cut` refuses until one exists (#492)' });
|
|
379
|
+
} else if (!tags.some((t) => FINAL_TAG.test(t))) {
|
|
380
|
+
steps.push({ n: 6, text: 'First final: none yet, and `colab release cut` refuses with no final to bump from — the first final is the operator\'s to set (e.g. `git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0`); an agent tags it only when told to (#492)' });
|
|
381
|
+
}
|
|
382
|
+
return steps;
|
|
383
|
+
}
|
|
384
|
+
|
|
312
385
|
function remainingSteps(ctx = {}) {
|
|
313
386
|
const steps = [];
|
|
314
387
|
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
@@ -327,6 +400,7 @@ function remainingSteps(ctx = {}) {
|
|
|
327
400
|
}
|
|
328
401
|
steps.push(
|
|
329
402
|
{ n: 6, text: "Make sure CI meets §7's outcome — `colab template <name>`, step 6" },
|
|
403
|
+
...(ctx.releaseRung || []),
|
|
330
404
|
{ n: 7, text: 'Register the repo — `colab register`, step 7' },
|
|
331
405
|
{ n: 8, text: 'Leave existing branches alone — nothing to do, step 8' },
|
|
332
406
|
{ n: 9, text: 'Do not create `dev` unless genuinely Tier A or Tier C — nothing to do, step 9' },
|
|
@@ -438,6 +512,13 @@ function detect(io, extra = {}) {
|
|
|
438
512
|
? detectMigrationCandidates(cfg, extra.trackedFiles)
|
|
439
513
|
: null;
|
|
440
514
|
|
|
515
|
+
// #492: on exposure: released, step 6 also wires the release rung.
|
|
516
|
+
const workflowTexts = {};
|
|
517
|
+
for (const f of workflows) workflowTexts[f] = io.readFile(`.github/workflows/${f}`) || '';
|
|
518
|
+
const stackFiles = ['composer.json', 'Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml']
|
|
519
|
+
.filter((f) => io.readFile(f) !== null);
|
|
520
|
+
const releaseRung = releaseRungSteps({ cfg, workflowTexts, tags: io.tags ? io.tags() : null, stackFiles });
|
|
521
|
+
|
|
441
522
|
return {
|
|
442
523
|
descriptorExists: io.readFile('.github/project.yml') !== null,
|
|
443
524
|
cfg,
|
|
@@ -456,7 +537,7 @@ function detect(io, extra = {}) {
|
|
|
456
537
|
upstreamAgentFiles,
|
|
457
538
|
inheritedCodeowners,
|
|
458
539
|
migrations,
|
|
459
|
-
remaining: remainingSteps({ migrations, fork, upstreamAgentFiles }),
|
|
540
|
+
remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
|
|
460
541
|
};
|
|
461
542
|
}
|
|
462
543
|
|
|
@@ -1070,6 +1151,7 @@ module.exports = {
|
|
|
1070
1151
|
deriveTier,
|
|
1071
1152
|
deriveConsequences,
|
|
1072
1153
|
remainingSteps,
|
|
1154
|
+
releaseRungSteps,
|
|
1073
1155
|
detectUpstreamAgentFiles,
|
|
1074
1156
|
detectMigrationCandidates,
|
|
1075
1157
|
detect,
|