@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0
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/README.md +19 -0
- package/README.vi.md +19 -0
- package/audit/audit.mjs +59 -15
- package/package.json +1 -1
- package/templates/README.md +64 -2
- package/templates/ci-laravel-heavy.yml +370 -0
- package/templates/ci-laravel.yml +27 -218
- package/templates/ci-node-heavy.yml +293 -0
- package/templates/ci-node.yml +23 -202
- package/templates/ci-python-heavy.yml +302 -0
- package/templates/ci-python.yml +26 -207
- package/templates/release-auto.yml +70 -1
- package/templates/release-tag.yml +20 -3
- package/tools/colab +463 -38
- package/tools/lib/disposition.js +27 -10
- package/tools/lib/docs-only.js +76 -21
- package/tools/lib/git.js +6 -1
- package/tools/lib/integration-profile.js +161 -0
- package/tools/lib/release-cut.js +10 -0
- package/tools/lib/release-finalize.js +9 -2
- package/tools/lib/secret-scan.js +132 -0
- package/tools/lib/ship-batch.js +71 -2
- package/tools/lib/stamp.js +16 -1
package/README.md
CHANGED
|
@@ -93,6 +93,25 @@ with no agent and no other tool.
|
|
|
93
93
|
- **Not a maturity model.** No answer here ranks a repo above another. A repo
|
|
94
94
|
with no production is not a worse repo; it is a repo with fewer gates.
|
|
95
95
|
|
|
96
|
+
### Scope — and what is frozen
|
|
97
|
+
|
|
98
|
+
The handbook's scope is **how code lands on git**: tiers and exposure,
|
|
99
|
+
`project.yml`, branches and commits, branch CI, worktrees and ports, the git
|
|
100
|
+
claim ref, ship and release mechanics, CI templates, conformance, adoption and
|
|
101
|
+
`solo`. Since 2026-10-14
|
|
102
|
+
([#604](https://github.com/futurelastic/colab-handbook/issues/604)), the surface
|
|
103
|
+
that decides *who holds an issue, what was decided, what may start, and who may
|
|
104
|
+
do an act* is **frozen**: claims recorded on the issue, readiness, `Filed-by`
|
|
105
|
+
provenance, decision records, and every `COLAB_HUMAN=1` gate except `solo`. It
|
|
106
|
+
will move to a separate decision, work and gate layer that adopters run. It
|
|
107
|
+
keeps working, bug fixes still land, and nothing is removed before its
|
|
108
|
+
replacement has run in production for 7 days. The notice heads
|
|
109
|
+
[`CONVENTIONS.md` §5](CONVENTIONS.md#5-claiming-work--how-to-say-im-on-this); the full
|
|
110
|
+
list is in [ADR 604](docs/adr/604-scope-freeze.md).
|
|
111
|
+
|
|
112
|
+
**Contributing:** a proposal for a new feature in a frozen area is refused,
|
|
113
|
+
with a pointer to [#604](https://github.com/futurelastic/colab-handbook/issues/604).
|
|
114
|
+
|
|
96
115
|
## Your first session
|
|
97
116
|
|
|
98
117
|
A unit of work goes round one loop. Each step is a skill, invoked by name in an
|
package/README.vi.md
CHANGED
|
@@ -92,6 +92,25 @@ khác.
|
|
|
92
92
|
này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
|
|
93
93
|
repo có ít cổng hơn.
|
|
94
94
|
|
|
95
|
+
### Phạm vi — và phần bị đóng băng
|
|
96
|
+
|
|
97
|
+
Phạm vi của handbook là **cách code vào git**: tier và exposure,
|
|
98
|
+
`project.yml`, branch và commit, CI của branch, worktree và port, claim ref
|
|
99
|
+
trên git, cơ chế ship và release, template CI, kiểm tra tuân thủ, adopt và
|
|
100
|
+
`solo`. Từ 2026-10-14
|
|
101
|
+
([#604](https://github.com/futurelastic/colab-handbook/issues/604)), phần quyết
|
|
102
|
+
định *ai giữ issue, đã quyết gì, việc gì được bắt đầu, và ai được làm một hành
|
|
103
|
+
động* bị **đóng băng**: claim ghi trên issue, readiness, provenance `Filed-by`,
|
|
104
|
+
decision record, và mọi cổng `COLAB_HUMAN=1` trừ `solo`. Phần này sẽ chuyển
|
|
105
|
+
sang một lớp quyết định, công việc và cổng riêng do bên adopt tự chạy. Nó vẫn
|
|
106
|
+
chạy, bug fix vẫn được nhận, và không gì bị gỡ trước khi phần thay thế đã chạy
|
|
107
|
+
production đủ 7 ngày. Thông báo nằm ở đầu
|
|
108
|
+
[`CONVENTIONS.md` §5](CONVENTIONS.md#5-claiming-work--how-to-say-im-on-this); danh sách
|
|
109
|
+
đầy đủ ở [ADR 604](docs/adr/604-scope-freeze.md).
|
|
110
|
+
|
|
111
|
+
**Đóng góp:** đề xuất tính năng mới trong vùng bị đóng băng sẽ bị từ chối, kèm
|
|
112
|
+
đường dẫn tới [#604](https://github.com/futurelastic/colab-handbook/issues/604).
|
|
113
|
+
|
|
95
114
|
## Phiên làm việc đầu tiên
|
|
96
115
|
|
|
97
116
|
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
|
package/audit/audit.mjs
CHANGED
|
@@ -122,6 +122,7 @@ const installRoute = require("../tools/lib/install-route.js");
|
|
|
122
122
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
123
123
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
124
124
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
125
|
+
const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
|
|
125
126
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
126
127
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
127
128
|
const batchHistory = require("../tools/lib/batch-history.js"); // #556
|
|
@@ -157,7 +158,7 @@ const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
|
|
|
157
158
|
const identity = require("../tools/lib/identity.js");
|
|
158
159
|
const {
|
|
159
160
|
handbookInfo, templateNames, templateChangedSince, cmpParts, cmpSemver,
|
|
160
|
-
parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, looksLikeHandbookClaude,
|
|
161
|
+
parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, isCiProvenance, looksLikeHandbookClaude,
|
|
161
162
|
} = stamp;
|
|
162
163
|
|
|
163
164
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
@@ -417,23 +418,29 @@ function satisfiesConstraint(version, constraint) {
|
|
|
417
418
|
|
|
418
419
|
// Run all stamp/reconciliation checks for one repo, pushing findings via fail/warn.
|
|
419
420
|
// Silent when there is nothing to say (the common, healthy case).
|
|
420
|
-
function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", missingAxes = [], predatesAxes = [], writesRaw = null } = {}) {
|
|
421
|
+
function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", missingAxes = [], predatesAxes = [], writesRaw = null, suggest = () => {} } = {}) {
|
|
421
422
|
const cur = hb.version;
|
|
422
423
|
|
|
423
424
|
const compareStamp = (kind, name, stampVersion, files, { isCi = false } = {}) => {
|
|
424
425
|
// Deactivated while the handbook is untagged — a global note already says so.
|
|
425
426
|
if (hb.untagged || !hb.hasGit) return;
|
|
427
|
+
// #607: a CI template is GUIDANCE. How an adopter's CI produces its verdict is the adopter's
|
|
428
|
+
// business; the handbook enforces only what `colab ship` reads (checked elsewhere in this file:
|
|
429
|
+
// trunk CI-gated, the branch trigger under gate: ci, ship-batch, the round-trip job name). So
|
|
430
|
+
// every stamp observation on a `ci-*` copy is information — never a fail, never a warn.
|
|
431
|
+
const warn_ = isCi ? suggest : warn;
|
|
432
|
+
const fail_ = isCi ? suggest : fail;
|
|
426
433
|
if (name !== null && !tmplNames.has(name)) {
|
|
427
|
-
|
|
434
|
+
warn_(`${kind} stamped @ ${stampVersion} names unknown template "${name}" — not in handbook templates/`);
|
|
428
435
|
return;
|
|
429
436
|
}
|
|
430
437
|
if (cmpSemver(stampVersion, cur) > 0) {
|
|
431
|
-
|
|
438
|
+
warn_(`${kind} stamped @ ${stampVersion} is NEWER than handbook current ${cur} — clock skew or a hand-edited stamp`);
|
|
432
439
|
return;
|
|
433
440
|
}
|
|
434
441
|
const { verifiable, changed, ruleNeutral } = templateChangedSince(HANDBOOK_ROOT, files, stampVersion);
|
|
435
442
|
if (!verifiable) {
|
|
436
|
-
|
|
443
|
+
warn_(`${kind} stamped @ ${stampVersion}, a version not in this handbook checkout — cannot verify drift (fetch tags, or re-copy)`);
|
|
437
444
|
return;
|
|
438
445
|
}
|
|
439
446
|
if (changed) {
|
|
@@ -452,8 +459,9 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
|
|
|
452
459
|
// template stays a hard fail regardless of the declaration, for the identical reason
|
|
453
460
|
// `isCi` already overrides ceremony above. Declaring nothing (the default) is unaffected
|
|
454
461
|
// — that repo gets exactly today's fail.
|
|
455
|
-
if (
|
|
456
|
-
else if (
|
|
462
|
+
if (isCi) fail_(`${kind} copied @ ${stampVersion} — template has a newer suggestion (${cur}); adopt it if it helps: \`colab update\` shows the diff`);
|
|
463
|
+
else if (ruleNeutral) warn(`${msg} (declared rule-neutral at commit time — see CONVENTIONS.md §8)`);
|
|
464
|
+
else if (ceremony === "light") warn(`${msg} (ceremony: light — advisory)`);
|
|
457
465
|
else fail(msg);
|
|
458
466
|
}
|
|
459
467
|
};
|
|
@@ -473,8 +481,11 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
|
|
|
473
481
|
// that name exists). `unstampedFinding` is shared with `colab update` so the two tools
|
|
474
482
|
// cannot drift on this. The `unrelated` finding is deliberately NOT raised here: it has no
|
|
475
483
|
// action, and the audit reports drift, not reassurance.
|
|
476
|
-
const
|
|
477
|
-
|
|
484
|
+
const prov = workflowProvenance(text, stem, tmplNames);
|
|
485
|
+
const finding = unstampedFinding(prov);
|
|
486
|
+
// #607: an unstamped CI copy is the adopter's own CI — information, like any CI-template drift.
|
|
487
|
+
const isCiCopy = isCiProvenance(prov); // the bare import: `stamp` is shadowed in this loop
|
|
488
|
+
if (finding && finding.state === 'unstamped') (isCiCopy ? suggest : warn)(`${wf} unstamped — ${finding.reason}`);
|
|
478
489
|
}
|
|
479
490
|
}
|
|
480
491
|
|
|
@@ -1497,13 +1508,16 @@ function auditRepoInner(target, ctx) {
|
|
|
1497
1508
|
if (!ifl.valid) fail(ifl.reason);
|
|
1498
1509
|
}
|
|
1499
1510
|
|
|
1500
|
-
// ---- ci-docs-skip (#570)
|
|
1501
|
-
//
|
|
1502
|
-
//
|
|
1503
|
-
//
|
|
1511
|
+
// ---- ci-docs-skip (#570, #606) ---------------------------------------------
|
|
1512
|
+
// The docs-only path list (tools/lib/docs-only.js parseCiDocsSkip). ON BY DEFAULT (#606): absent
|
|
1513
|
+
// = on, a list = on with those paths excluded (a change to one is not docs-only), `off` = off.
|
|
1514
|
+
// `colab ship` reads it to decide a docs-only change needs no CI; the CI templates' legacy guard
|
|
1515
|
+
// reads the same list. Reported as the exception list (`[]` when absent), `"off"`, or null when
|
|
1516
|
+
// invalid. An invalid value fails: every reader takes it as "not docs-only", so it silently
|
|
1517
|
+
// opts the repo out.
|
|
1504
1518
|
{
|
|
1505
1519
|
const ds = docsOnlyLib.parseCiDocsSkip(cfg);
|
|
1506
|
-
info.ciDocsSkip = ds.
|
|
1520
|
+
info.ciDocsSkip = !ds.valid ? null : ds.on ? ds.exclude : "off";
|
|
1507
1521
|
if (!ds.valid) fail(ds.reason);
|
|
1508
1522
|
}
|
|
1509
1523
|
|
|
@@ -1758,6 +1772,31 @@ function auditRepoInner(target, ctx) {
|
|
|
1758
1772
|
}
|
|
1759
1773
|
}
|
|
1760
1774
|
|
|
1775
|
+
// ---- integration-profile / heavy-workflow (#610) ---------------------------
|
|
1776
|
+
// Read through tools/lib/integration-profile.js — the module `colab ship` and `colab release` use,
|
|
1777
|
+
// so the audit and the gates cannot disagree about a value. A malformed value makes the gates fail
|
|
1778
|
+
// closed to release-heavy (ship unchanged), which is safe but silent, so it fails here. The `live`
|
|
1779
|
+
// restriction fails only a DECLARED qualify/release-heavy; a repo that never declared gets a
|
|
1780
|
+
// suggestion, never a new failure.
|
|
1781
|
+
let integrationSuggestion = null;
|
|
1782
|
+
if (cfg) {
|
|
1783
|
+
const ipCfg = integrationProfile.parseProfile(cfg);
|
|
1784
|
+
const hwCfg = integrationProfile.parseHeavyWorkflow(cfg);
|
|
1785
|
+
if (!ipCfg.valid) fail(`${ipCfg.reason} — see project.schema.md, integration-profile`);
|
|
1786
|
+
if (!hwCfg.valid) fail(`${hwCfg.reason} — see project.schema.md, heavy-workflow`);
|
|
1787
|
+
if (ipCfg.valid) {
|
|
1788
|
+
const lr = integrationProfile.liveRestriction({ profile: ipCfg.profile, declared: ipCfg.declared, exposure: authority ? authority.exposure : null, deploy });
|
|
1789
|
+
if (lr && lr.level === "fail") fail(lr.message);
|
|
1790
|
+
else if (lr) integrationSuggestion = lr.message;
|
|
1791
|
+
if (ipCfg.profile === "promote" && (!trunk || trunk === "main")) {
|
|
1792
|
+
fail(`integration-profile: promote gates the promotion into main with the heavy lane, but trunk is ${JSON.stringify(trunk)} — there is no promotion to gate. Choose gated, qualify or release-heavy (CONVENTIONS.md §7, Integration profiles)`);
|
|
1793
|
+
}
|
|
1794
|
+
if (ipCfg.profile === "gated" && hwCfg.valid && !workflows.includes(hwCfg.file)) {
|
|
1795
|
+
warn(`integration-profile: gated but no .github/workflows/${hwCfg.file} — colab ship refuses every code landing until a heavy lane exists (templates/ci-<stack>-heavy.yml), or name it with heavy-workflow:`);
|
|
1796
|
+
}
|
|
1797
|
+
}
|
|
1798
|
+
}
|
|
1799
|
+
|
|
1761
1800
|
// Additive `--json` keys only (#144's oracle: "`tier` continues to report the DECLARED
|
|
1762
1801
|
// letter... New keys are additive"). `axisOfRecord` names which key governs
|
|
1763
1802
|
// ('exposure' | 'tier-legacy' | 'none' | null when project.yml itself did not parse);
|
|
@@ -2093,7 +2132,10 @@ function auditRepoInner(target, ctx) {
|
|
|
2093
2132
|
// was ever asked.
|
|
2094
2133
|
const missingAxes = cfg ? stamp.AXES.filter((a) => !(a in cfg)) : [];
|
|
2095
2134
|
info.predatesAxes = [];
|
|
2096
|
-
|
|
2135
|
+
info.suggestions = [];
|
|
2136
|
+
const suggest = (t) => info.suggestions.push(t);
|
|
2137
|
+
if (integrationSuggestion) suggest(integrationSuggestion); // #610
|
|
2138
|
+
if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
|
|
2097
2139
|
|
|
2098
2140
|
// ---- repository metadata identity scan (#228 part 4) ----------------------
|
|
2099
2141
|
// Explicitly NOT gated on isSelf: the handbook is public, its description and topics are
|
|
@@ -3345,6 +3387,8 @@ function report(results, opts, ctx) {
|
|
|
3345
3387
|
else if (r.adoption === "local") lines.push(`⌂ adopted locally, not committed — descriptor hidden by .git/info/exclude; a repo the fleet does not own (CONVENTIONS.md §9)${r.clean ? " ✓" : ""}`);
|
|
3346
3388
|
else if (r.clean) lines.push("✓");
|
|
3347
3389
|
r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
|
|
3390
|
+
// #607: CI-template drift — information, not a finding, so it never changes clean/ok.
|
|
3391
|
+
(r.suggestions || []).forEach((s) => lines.push(`▸ ${s}`));
|
|
3348
3392
|
// #556: the measured picture — information, not a finding, so it never changes clean/ok.
|
|
3349
3393
|
if (r.batchHistory?.status === "read") {
|
|
3350
3394
|
r.batchHistory.picture.forEach((l) => lines.push(`▸ ${l}`));
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -12,12 +12,71 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
12
12
|
> workflow that silently changes under a hundred repos is the failure mode we are
|
|
13
13
|
> avoiding.
|
|
14
14
|
|
|
15
|
+
**The CI templates are guidance, not enforcement (#607).** Change your copy in any way you
|
|
16
|
+
like. The audit reports a difference from a CI template as a `▸` suggestion only, never a fail
|
|
17
|
+
or warn. The handbook enforces only what `colab ship` reads from your CI
|
|
18
|
+
([CONVENTIONS §7, *What ship reads*](../CONVENTIONS.md#what-ship-reads--the-ci-contract-607)):
|
|
19
|
+
- a run on every push to trunk;
|
|
20
|
+
- a run on a branch push where `gate: authoritative: ci`;
|
|
21
|
+
- a run on `ship-batch/**` where `ship-batch` is above 1;
|
|
22
|
+
- a `Migration round-trip…` job where `migration-grant: reviewer`.
|
|
23
|
+
|
|
24
|
+
### Two lanes — light on every merge, heavy on official builds and nightly
|
|
25
|
+
|
|
26
|
+
| Lane | Template → copy | Runs | What |
|
|
27
|
+
|---|---|---|---|
|
|
28
|
+
| **light** | `ci-<stack>.yml` → `ci.yml` | every push (branch and trunk); the lane `colab ship` reads | secret scan, build, typecheck/lint, the fast tests — aim for under 5 minutes at p50 |
|
|
29
|
+
| **heavy** | `ci-<stack>-heavy.yml` → `ci-heavy.yml` | nightly on trunk's tip (skipped when trunk has not moved since the last green nightly), at every release candidate and tag, and by hand — **never per merge** | the whole suite including heavy-marked tests, integration, browser/e2e, load |
|
|
30
|
+
|
|
31
|
+
- **The adopter marks which tests are heavy; an unmarked test is light**, so nothing stops
|
|
32
|
+
running per merge until someone decides it should.
|
|
33
|
+
- Node: a `test:heavy` script, for example over `*.heavy.test.*` files that `test` does not run.
|
|
34
|
+
- Python: the pytest marker `heavy`.
|
|
35
|
+
- Laravel: the Pest/PHPUnit group `heavy`.
|
|
36
|
+
- **The heavy lane gates official builds.** `release-tag.yml` calls it (`workflow_call`) at the
|
|
37
|
+
tag and publishes only on green. `release-auto.yml` dispatches it at every new candidate and
|
|
38
|
+
finalizes only on its green run at that candidate's exact sha. With no `ci-heavy.yml`, both
|
|
39
|
+
skip the gate.
|
|
40
|
+
- **A red nightly is a trunk finding, not a merge block.** It files one `trunk-red` issue per
|
|
41
|
+
lane, naming the commit range since the last green nightly. An open issue for the lane
|
|
42
|
+
suppresses a new one. If the issue list cannot be read, it files nothing and fails the job.
|
|
43
|
+
- **Exposure sets the bar.** `live`/`released` repos run the heavy lane before every official
|
|
44
|
+
build. `none`/`self` repos may run it nightly only.
|
|
45
|
+
- **The trade-off:** a defect the light lane misses can sit on trunk for up to a day. A repo that
|
|
46
|
+
cannot accept that picks another `integration-profile:` (below).
|
|
47
|
+
|
|
48
|
+
### Where each integration profile wires the heavy lane (#610)
|
|
49
|
+
|
|
50
|
+
`integration-profile:` in `project.yml` ([CONVENTIONS §7](../CONVENTIONS.md#integration-profiles--where-the-heavy-lane-runs-and-what-a-green-trunk-promises-610))
|
|
51
|
+
decides when the heavy lane runs. The light `ci.yml` is the same under every profile; only the heavy
|
|
52
|
+
file's triggers change:
|
|
53
|
+
|
|
54
|
+
| Profile | What to change in `ci-heavy.yml` |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `release-heavy` (absent) | nothing — the template as copied: nightly, plus every official build |
|
|
57
|
+
| `gated` | nothing — `colab ship` dispatches it (`workflow_dispatch`, input `ref` = the sha) at each landing's branch or batch head, and lands only on its green. Keep `workflow_dispatch` and its `ref` input. |
|
|
58
|
+
| `qualify` | the `schedule` cron becomes the clock: every few hours on trunk's tip (e.g. `"23 */4 * * *"`), still skipped when trunk has not moved |
|
|
59
|
+
| `promote` | dispatch it on the trunk tip before `colab promote` (`gh workflow run ci-heavy.yml --ref dev -f ref=<sha>`) — promote refuses until it is green |
|
|
60
|
+
|
|
61
|
+
Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `project.yml`.
|
|
62
|
+
- **Traps the heavy template already handles:**
|
|
63
|
+
- It has no push or `pull_request` trigger, so ship never counts its run.
|
|
64
|
+
- The `plan` job, not an all-skipped run, is what concludes `success` on a skipped nightly.
|
|
65
|
+
- It has no `concurrency` group, so no heavy run is ever cancelled.
|
|
66
|
+
- The nightly never commits.
|
|
67
|
+
- The tested sha is in the job name, `Full suite @ <sha>`, which is how the next nightly knows
|
|
68
|
+
whether trunk moved.
|
|
69
|
+
- **A docs-only change needs no CI wait:** `colab ship` decides that from the diff (#606). The
|
|
70
|
+
light templates show a commented `paths-ignore` for docs as an option; the old in-workflow
|
|
71
|
+
docs-only guard is gone.
|
|
72
|
+
|
|
15
73
|
## What each template is for
|
|
16
74
|
|
|
17
75
|
| File | Copy to | For | Notes |
|
|
18
76
|
|---|---|---|---|
|
|
19
77
|
| `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. |
|
|
20
78
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
79
|
+
| `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
|
|
21
80
|
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
|
|
22
81
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
23
82
|
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
@@ -87,6 +146,8 @@ schema *before* the change — once more, the way a deploy lands new migrations
|
|
|
87
146
|
that predates them. The schema after both passes must match. Two things to know before
|
|
88
147
|
trusting a green run:
|
|
89
148
|
|
|
149
|
+
- **A `down()` that sqlite cannot run, or one that does not undo its `up()`**, turns a leg red —
|
|
150
|
+
and nothing else in CI ever runs `down()`.
|
|
90
151
|
- **Both legs matter.** The engines disagree: a `NOT NULL` column added without a default
|
|
91
152
|
fails on sqlite when rows exist, while MariaDB accepts it and silently writes `''` into
|
|
92
153
|
every existing row. A deploy-engine leg at a version production does not run proves
|
|
@@ -144,6 +205,7 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
|
|
|
144
205
|
```sh
|
|
145
206
|
colab template # list templates + handbook version
|
|
146
207
|
colab template ci-node --dest .github/workflows/ci.yml
|
|
208
|
+
colab template ci-node-heavy --dest .github/workflows/ci-heavy.yml # the heavy lane, optional
|
|
147
209
|
colab template release-tag --dest .github/workflows/release.yml
|
|
148
210
|
colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
|
|
149
211
|
colab template deploy-container --dest .github/workflows/deploy-container.yml
|
|
@@ -270,8 +332,8 @@ silent updates, just an honest report that you are behind.
|
|
|
270
332
|
If you're the one editing a template *in this repo* and the change touches no rule at
|
|
271
333
|
all — a typo, a broken hyperlink, a comment — write `Rule-Neutral: yes` as a trailer on
|
|
272
334
|
that commit. Every adopter's drift finding for it then downgrades to a warn instead of a
|
|
273
|
-
hard fail, but only if **every** commit since their stamp declared it
|
|
274
|
-
is
|
|
335
|
+
hard fail, but only if **every** commit since their stamp declared it. A `ci-*` template's
|
|
336
|
+
drift is only ever a suggestion (#607), so the trailer is moot there. Full contract: [CONVENTIONS.md §8](../CONVENTIONS.md#8-conformance-and-reconciliation).
|
|
275
337
|
|
|
276
338
|
## Keeping honest
|
|
277
339
|
|