@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.0-rc.9
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 +3 -2
- package/README.vi.md +3 -2
- package/package.json +1 -1
- package/templates/README.md +2 -2
- package/templates/pre-push-guard +21 -1
- package/templates/release-auto.yml +8 -3
- package/tools/colab +49 -10
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/stamp.js +38 -1
package/README.md
CHANGED
|
@@ -216,14 +216,15 @@ window between a CLI commit and the next tag, and the advertised remedy copies
|
|
|
216
216
|
*from* that same working tree — so on a machine developing the handbook it
|
|
217
217
|
advised services to adopt untagged code.) It never rewrites the copy, not even
|
|
218
218
|
with `--apply`: that is the toolchain your running services are executing.
|
|
219
|
-
`colab --version` says which of the two you are talking to
|
|
219
|
+
`colab --version` says which of the two you are talking to (or `npm package` for an
|
|
220
|
+
`npx`/`npm i` install), and prints that install's version. The frozen copy carries
|
|
220
221
|
`tools/` only, so `colab template` refuses there — run it from the working tree.
|
|
221
222
|
|
|
222
223
|
**3. Verify, and register your repos.**
|
|
223
224
|
|
|
224
225
|
```sh
|
|
225
226
|
colab --help # not found? fix your PATH — step 2 prints the exact line
|
|
226
|
-
colab --version # which colab is this
|
|
227
|
+
colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
|
|
227
228
|
colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
|
|
228
229
|
node audit/audit.mjs # a conformance report across the whole fleet
|
|
229
230
|
colab update # stamped copies that fell behind — the frozen CLI included
|
package/README.vi.md
CHANGED
|
@@ -208,13 +208,14 @@ mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag k
|
|
|
208
208
|
phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
|
|
209
209
|
triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
|
|
210
210
|
ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
|
|
211
|
-
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào
|
|
211
|
+
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
|
|
212
|
+
cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
|
|
212
213
|
|
|
213
214
|
**3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
|
|
214
215
|
|
|
215
216
|
```sh
|
|
216
217
|
colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
|
|
217
|
-
colab --version # colab nào đây
|
|
218
|
+
colab --version # colab nào đây — working tree, bản đóng băng hay npm package — và phiên bản của nó
|
|
218
219
|
$EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
|
|
219
220
|
node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
|
|
220
221
|
colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
20
20
|
| `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. |
|
|
21
21
|
| `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
22
|
| `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
|
-
| `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, from a
|
|
23
|
+
| `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, 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. |
|
|
24
24
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
25
25
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path for a service's `init`. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
26
26
|
| `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
|
|
@@ -69,7 +69,7 @@ a workflow.
|
|
|
69
69
|
|
|
70
70
|
| File | Copy to | For | Notes |
|
|
71
71
|
|---|---|---|---|
|
|
72
|
-
| `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes. Reads `project.yml`; missing descriptor → allows, with a warning. |
|
|
72
|
+
| `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
|
|
73
73
|
| `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
|
|
74
74
|
| `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
|
|
75
75
|
| `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
|
package/templates/pre-push-guard
CHANGED
|
@@ -9,10 +9,14 @@
|
|
|
9
9
|
# COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
|
|
10
10
|
# The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
|
|
11
11
|
# automatically — main there is what promotion deploys, so it needs the gate most.
|
|
12
|
+
# RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
|
|
13
|
+
# `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
|
|
14
|
+
# they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
|
|
15
|
+
# uses a branch of either name for something else edits its copy of this hook (copy-and-own).
|
|
12
16
|
# On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
|
|
13
17
|
# Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
|
|
14
18
|
#
|
|
15
|
-
# The
|
|
19
|
+
# The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
|
|
16
20
|
# the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
|
|
17
21
|
# process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
|
|
18
22
|
# The refusal messages below therefore name the remedy and not the variable (#322) — this header is
|
|
@@ -51,10 +55,13 @@ integration=$(awk '
|
|
|
51
55
|
pushing_trunk=0
|
|
52
56
|
pushing_main=0
|
|
53
57
|
pushing_line=""
|
|
58
|
+
pushing_channel=""
|
|
54
59
|
while read -r _localref _localsha remoteref _remotesha; do
|
|
55
60
|
case "${remoteref:-}" in
|
|
56
61
|
refs/heads/"$trunk") pushing_trunk=1 ;;
|
|
57
62
|
refs/heads/main) pushing_main=1 ;;
|
|
63
|
+
refs/heads/next) pushing_channel=next ;;
|
|
64
|
+
refs/heads/stable) pushing_channel=stable ;;
|
|
58
65
|
esac
|
|
59
66
|
for line in $integration; do
|
|
60
67
|
if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
|
|
@@ -105,6 +112,19 @@ if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}
|
|
|
105
112
|
exit 1
|
|
106
113
|
fi
|
|
107
114
|
|
|
115
|
+
# RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
|
|
116
|
+
if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
117
|
+
echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
|
|
118
|
+
echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
|
|
119
|
+
if [ "$pushing_channel" = next ]; then
|
|
120
|
+
echo " colab release cut # a new candidate fast-forwards 'next'" >&2
|
|
121
|
+
else
|
|
122
|
+
echo " colab release finalize # a new final fast-forwards 'stable'" >&2
|
|
123
|
+
fi
|
|
124
|
+
echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
|
|
125
|
+
exit 1
|
|
126
|
+
fi
|
|
127
|
+
|
|
108
128
|
# MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
|
|
109
129
|
if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
110
130
|
echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
|
|
@@ -124,9 +124,14 @@ concurrency:
|
|
|
124
124
|
permissions: {}
|
|
125
125
|
|
|
126
126
|
env:
|
|
127
|
-
# EDIT: the handbook
|
|
128
|
-
#
|
|
129
|
-
|
|
127
|
+
# EDIT: the handbook ref whose colab CLI makes the release decisions — a CHANNEL or a
|
|
128
|
+
# version tag (CONVENTIONS.md §6, *Release channels*, #445):
|
|
129
|
+
# stable the newest final release — the default; it moves forward as finals are cut,
|
|
130
|
+
# and that release's notes say what changed
|
|
131
|
+
# next the newest candidate (vX.Y.Z-rc.N) — the fast channel
|
|
132
|
+
# vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
|
|
133
|
+
# a template
|
|
134
|
+
HANDBOOK_REF: "stable"
|
|
130
135
|
HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
|
|
131
136
|
|
|
132
137
|
jobs:
|
package/tools/colab
CHANGED
|
@@ -63,6 +63,7 @@ const releasePolicy = require('./lib/release-policy');
|
|
|
63
63
|
const workflowTriggers = require('./lib/workflow-triggers');
|
|
64
64
|
const releaseCut = require('./lib/release-cut');
|
|
65
65
|
const releaseFinalize = require('./lib/release-finalize');
|
|
66
|
+
const releaseChannel = require('./lib/release-channel');
|
|
66
67
|
const shippedBranch = require('./lib/shipped-branch');
|
|
67
68
|
const shipRoles = require('./lib/ship-roles'); // #372
|
|
68
69
|
const refsBrake = require('./lib/refs-brake'); // #385
|
|
@@ -1244,6 +1245,11 @@ Every cut also publishes the candidate's GitHub pre-release (#443): notes = the
|
|
|
1244
1245
|
since the last final plus the tag message. Best-effort — a failure warns (--json published.ok false)
|
|
1245
1246
|
and never undoes the pushed tag.
|
|
1246
1247
|
|
|
1248
|
+
Every cut also fast-forwards the release channel \`next\` — a branch, always the newest candidate
|
|
1249
|
+
(#445) — to the candidate's commit, pushed with COLAB_RELEASE=1 (what pre-push-guard lets through).
|
|
1250
|
+
Forward only, never forced: a \`next\` that is not an ancestor of the candidate is reported and left
|
|
1251
|
+
alone. Best-effort like the pre-release (--json channel.ok false); the tag stands either way.
|
|
1252
|
+
|
|
1247
1253
|
Needs origin reachable (the tag is recorded there) and gh usable (CI, suite and switch markers are
|
|
1248
1254
|
read from GitHub). Exit code: 0 when a candidate was cut (or, with --dry, would be), or an --auto
|
|
1249
1255
|
no-op; 1 when refused.
|
|
@@ -1508,11 +1514,16 @@ function cmdReleaseCut(argv) {
|
|
|
1508
1514
|
created = true;
|
|
1509
1515
|
published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message });
|
|
1510
1516
|
}
|
|
1517
|
+
// #445: the `next` channel names the newest candidate — fast-forwarded in the run that pushed it.
|
|
1518
|
+
// Best-effort like the pre-release: the tag already stands, so a channel that cannot move is reported.
|
|
1519
|
+
const channel = verdict.ok && verdict.tag
|
|
1520
|
+
? releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
|
|
1521
|
+
: null;
|
|
1511
1522
|
|
|
1512
1523
|
if (opts.json) {
|
|
1513
1524
|
print(JSON.stringify({
|
|
1514
1525
|
repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
|
|
1515
|
-
ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, version: verdict.version, bump: verdict.bump,
|
|
1526
|
+
ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
|
|
1516
1527
|
overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
|
|
1517
1528
|
}, null, 2));
|
|
1518
1529
|
return verdict.ok || verdict.noop ? 0 : 1;
|
|
@@ -1534,12 +1545,14 @@ function cmdReleaseCut(argv) {
|
|
|
1534
1545
|
print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
|
|
1535
1546
|
return 1;
|
|
1536
1547
|
}
|
|
1537
|
-
if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}
|
|
1548
|
+
if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
|
|
1538
1549
|
else {
|
|
1539
1550
|
print(`✓ cut ${verdict.tag} on ${at} and pushed it to ${remote} — a candidate, not a release; finalizing it is the release skill's.`);
|
|
1540
1551
|
if (published && published.ok) print(`✓ ${published.detail}`);
|
|
1541
1552
|
else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --prerelease --latest=false`);
|
|
1542
1553
|
}
|
|
1554
|
+
if (channel && channel.ok) print(`${opts.dry ? '·' : '✓'} ${channel.detail}`);
|
|
1555
|
+
else if (channel) warn(`${channel.detail} — the tag stands`);
|
|
1543
1556
|
return 0;
|
|
1544
1557
|
}
|
|
1545
1558
|
|
|
@@ -1627,6 +1640,10 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
|
|
|
1627
1640
|
in a commit since the previous final) gets one comment: "Released in vX.Y.Z"
|
|
1628
1641
|
(with --dry: every check passed, nothing written)
|
|
1629
1642
|
|
|
1643
|
+
A final also fast-forwards the release channel \`stable\` — a branch, always the newest final (#445)
|
|
1644
|
+
— to its commit; already-final repairs a \`stable\` a dead run left behind. Forward only, never
|
|
1645
|
+
forced, best-effort (--json channel); the final tag stands either way.
|
|
1646
|
+
|
|
1630
1647
|
Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
|
|
1631
1648
|
release-policy candidate tracking-issue release-hold regressions test-period trunk-green
|
|
1632
1649
|
ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
|
|
@@ -1664,6 +1681,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1664
1681
|
--json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
|
|
1665
1682
|
periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
|
|
1666
1683
|
skipped (--auto: [{tag, state, detail?}] — the other open candidates),
|
|
1684
|
+
channel (null, or {channel, ok, action, detail} — the stable move, #445),
|
|
1667
1685
|
announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
|
|
1668
1686
|
grant (null, or {issue, ruledBy} — the operator grant that made this final automatic) }
|
|
1669
1687
|
|
|
@@ -1838,6 +1856,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
1838
1856
|
|
|
1839
1857
|
// ---- writes ----
|
|
1840
1858
|
let tagged = false;
|
|
1859
|
+
let channel = null; // #445: { channel, ok, action, detail } once `stable` was (or could not be) moved
|
|
1841
1860
|
const comment = (num, fields, text) => {
|
|
1842
1861
|
const view = git.ghIssueView(repoAbs, num, ['comments']);
|
|
1843
1862
|
if (view && releaseFinalize.hasEvent(view.comments, fields)) return;
|
|
@@ -1880,6 +1899,13 @@ function cmdReleaseFinalize(argv) {
|
|
|
1880
1899
|
}
|
|
1881
1900
|
tagged = true;
|
|
1882
1901
|
}
|
|
1902
|
+
// #445: the `stable` channel names the newest final — moved by the run that tags it, and repaired
|
|
1903
|
+
// on the already-final resume (a run that died between the tag push and the move finishes it).
|
|
1904
|
+
if (tagged) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: cand.sha, label: cand.version });
|
|
1905
|
+
else if (verdict.state === 'already-final' && version0) {
|
|
1906
|
+
const finalTag = tags.find((t) => t.name === version0);
|
|
1907
|
+
if (finalTag) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: finalTag.sha, label: version0 });
|
|
1908
|
+
}
|
|
1883
1909
|
// The newest candidate is announced on its version's issue — on --auto with its own clock.
|
|
1884
1910
|
const tNew = version0 ? trackings.get(version0) : null;
|
|
1885
1911
|
if (newest && tNew && tNew.number) {
|
|
@@ -1929,7 +1955,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
1929
1955
|
lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
|
|
1930
1956
|
periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
|
|
1931
1957
|
state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
|
|
1932
|
-
skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null,
|
|
1958
|
+
skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null, channel,
|
|
1933
1959
|
}, null, 2));
|
|
1934
1960
|
} else {
|
|
1935
1961
|
print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
|
|
@@ -1942,6 +1968,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
1942
1968
|
print('');
|
|
1943
1969
|
print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
|
|
1944
1970
|
if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
|
|
1971
|
+
if (channel && channel.ok) print(`✓ ${channel.detail}`);
|
|
1972
|
+
else if (channel) warn(`${channel.detail} — the final tag stands`);
|
|
1945
1973
|
if (verdict.handoff) print(`\nThe final is a human act here. The one command, for a human to run:\n ${verdict.handoff}`);
|
|
1946
1974
|
}
|
|
1947
1975
|
// #423: on --auto, "nothing to do yet" (still testing, no candidate) is the workflow's ordinary output.
|
|
@@ -8187,20 +8215,31 @@ function readFrozenStamp(dir) {
|
|
|
8187
8215
|
function selfProvenance() {
|
|
8188
8216
|
const st = readFrozenStamp(__dirname);
|
|
8189
8217
|
if (st && st.name === stamp.FROZEN_STAMP_NAME) {
|
|
8190
|
-
return { frozen: true, version: st.version, source: __dirname, branch: null };
|
|
8218
|
+
return { kind: 'frozen', frozen: true, version: st.version, source: __dirname, branch: null };
|
|
8191
8219
|
}
|
|
8192
8220
|
const { root } = handbookPaths();
|
|
8221
|
+
// A registry install (npx, npm i) — before the git read below, which has no repo of its own to
|
|
8222
|
+
// answer from there and would walk up into whatever repo the npx cache happens to sit inside (#444).
|
|
8223
|
+
const pkg = stamp.npmPackageInfo(root);
|
|
8224
|
+
if (pkg) return { kind: 'npm', frozen: false, version: pkg.version, source: root, branch: null };
|
|
8193
8225
|
const hb = stamp.handbookInfo(root);
|
|
8194
8226
|
const br = stamp.gitIn(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
|
|
8195
|
-
return { frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
|
|
8227
|
+
return { kind: 'working-tree', frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
|
|
8228
|
+
}
|
|
8229
|
+
|
|
8230
|
+
/**
|
|
8231
|
+
* One version, from whichever provenance applies — there used to be a second, hard-coded
|
|
8232
|
+
* `colab 1.0.0` in front of it that no release ever moved (#444).
|
|
8233
|
+
*/
|
|
8234
|
+
function versionLine(self) {
|
|
8235
|
+
const where = self.kind === 'frozen' ? `frozen copy: ${self.source}`
|
|
8236
|
+
: self.kind === 'npm' ? `npm package: ${self.source}`
|
|
8237
|
+
: `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
|
|
8238
|
+
return `colab ${self.version} (${where})`;
|
|
8196
8239
|
}
|
|
8197
8240
|
|
|
8198
8241
|
function cmdVersion() {
|
|
8199
|
-
|
|
8200
|
-
const where = self.frozen
|
|
8201
|
-
? `frozen copy: ${self.source}`
|
|
8202
|
-
: `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
|
|
8203
|
-
return print(`colab 1.0.0 — colab-handbook ${self.version} (${where})`);
|
|
8242
|
+
return print(versionLine(selfProvenance()));
|
|
8204
8243
|
}
|
|
8205
8244
|
|
|
8206
8245
|
/** Current handbook version = nearest RELEASE tag (pre-releases skipped, #334); 'v0' before the first one. */
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/release-channel.js — the release CHANNELS `next` and `stable` (#445).
|
|
4
|
+
*
|
|
5
|
+
* Adopters follow a channel, not a hand-bumped pin:
|
|
6
|
+
*
|
|
7
|
+
* next always the newest CANDIDATE (vX.Y.Z-rc.N) — moved by `colab release cut`
|
|
8
|
+
* stable always the newest FINAL (vX.Y.Z) — moved by `colab release finalize`
|
|
9
|
+
*
|
|
10
|
+
* They are BRANCHES, not tags. A moving tag is refused by every clone that already fetched it
|
|
11
|
+
* (`would clobber existing tag`), and a non-semver tag can be read as "the newest version" by tag
|
|
12
|
+
* readers (`git describe --tags`, stamps). A branch moves cleanly and no tag reader sees it. Version
|
|
13
|
+
* tags stay immutable.
|
|
14
|
+
*
|
|
15
|
+
* Forward only. A channel is fast-forwarded to the commit the tag names, never forced: a channel
|
|
16
|
+
* that is not an ancestor of that commit is a finding (somebody moved it by hand, or a branch of the
|
|
17
|
+
* same name means something else in this repo) and is reported, never overwritten. `stable` lagging
|
|
18
|
+
* behind `next` is the design, not drift — they are two channels, each moving forward on its own.
|
|
19
|
+
*
|
|
20
|
+
* Best-effort, like the GitHub pre-release (#443): the tag is already on the remote when a channel
|
|
21
|
+
* moves, so a channel that could not move is reported (warning, --json `channel.ok: false`) and
|
|
22
|
+
* never a reason to undo the tag. The next cut / finalize retries, and finalize's already-final path
|
|
23
|
+
* repairs a `stable` a dead run left behind.
|
|
24
|
+
*
|
|
25
|
+
* The push carries COLAB_RELEASE=1 — the process-identity assertion templates/pre-push-guard reads
|
|
26
|
+
* for these two refs, the COLAB_SHIP precedent. Nothing else writes them.
|
|
27
|
+
*
|
|
28
|
+
* Two halves: decideMove is pure (facts in, an action out); moveChannel measures and writes through
|
|
29
|
+
* git, on the remote it is given.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
const git = require('./git');
|
|
33
|
+
|
|
34
|
+
const CHANNELS = Object.freeze({ next: 'next', stable: 'stable' });
|
|
35
|
+
/** The env a release command pushes a channel with — what pre-push-guard lets through. */
|
|
36
|
+
const RELEASE_ENV = 'COLAB_RELEASE';
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* What to do with `channel`, given where it is now and where it should be.
|
|
40
|
+
*
|
|
41
|
+
* current the channel's commit on the remote, or null when the branch does not exist
|
|
42
|
+
* target the commit the tag names
|
|
43
|
+
* currentIsAncestor current is an ancestor of target (a fast-forward)
|
|
44
|
+
* targetIsAncestor target is an ancestor of current (the channel is already past it)
|
|
45
|
+
*
|
|
46
|
+
* Returns { action: 'create' | 'move' | 'noop' | 'refuse', detail }.
|
|
47
|
+
*/
|
|
48
|
+
function decideMove({ channel, current, target, label, currentIsAncestor, targetIsAncestor }) {
|
|
49
|
+
const at = label ? `${label} (${short(target)})` : short(target);
|
|
50
|
+
if (!target) return { action: 'refuse', detail: `${channel}: no target commit` };
|
|
51
|
+
if (!current) return { action: 'create', detail: `${channel} created at ${at}` };
|
|
52
|
+
if (current === target) return { action: 'noop', detail: `${channel} already at ${at}` };
|
|
53
|
+
if (currentIsAncestor) return { action: 'move', detail: `${channel} fast-forwarded ${short(current)} -> ${at}` };
|
|
54
|
+
if (targetIsAncestor) return { action: 'noop', detail: `${channel} already past ${at} (at ${short(current)}) — a channel only moves forward` };
|
|
55
|
+
return {
|
|
56
|
+
action: 'refuse',
|
|
57
|
+
detail: `${channel} NOT moved: it is at ${short(current)}, which is not an ancestor of ${at} — a channel only fast-forwards; find out who moved it before moving it back by hand`,
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function short(sha) { return sha ? String(sha).slice(0, 7) : '—'; }
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Move `channel` on `remote` to `sha` (the commit `label`, a tag, names). Forward only, never forced.
|
|
65
|
+
* Returns { channel, ok, action, detail } — ok is false only on a refusal or a failed push/read.
|
|
66
|
+
* With `dry`, measures and reports what it would do, writing nothing.
|
|
67
|
+
*/
|
|
68
|
+
function moveChannel(repoAbs, { remote, channel, sha, label, dry = false, env = process.env }) {
|
|
69
|
+
const fail = (detail) => ({ channel, ok: false, action: 'refuse', detail });
|
|
70
|
+
const ls = git.git(['ls-remote', '--heads', remote, `refs/heads/${channel}`], repoAbs);
|
|
71
|
+
if (!ls.ok) return fail(`${channel} NOT moved: could not read it on ${remote} (${(ls.stderr || '').split('\n')[0] || ls.code})`);
|
|
72
|
+
const line = ls.stdout.split('\n').find((l) => l.endsWith(`\trefs/heads/${channel}`));
|
|
73
|
+
const current = line ? line.split('\t')[0] : null;
|
|
74
|
+
|
|
75
|
+
let currentIsAncestor = false;
|
|
76
|
+
let targetIsAncestor = false;
|
|
77
|
+
if (current && current !== sha) {
|
|
78
|
+
// The channel's commit is not necessarily local yet (a clone that never fetched the branch).
|
|
79
|
+
const have = git.git(['cat-file', '-e', `${current}^{commit}`], repoAbs);
|
|
80
|
+
if (!have.ok) {
|
|
81
|
+
const f = git.git(['fetch', '--quiet', remote, `refs/heads/${channel}`], repoAbs);
|
|
82
|
+
if (!f.ok) return fail(`${channel} NOT moved: could not fetch it from ${remote} to check it only moves forward (${(f.stderr || '').split('\n')[0] || f.code})`);
|
|
83
|
+
}
|
|
84
|
+
currentIsAncestor = git.git(['merge-base', '--is-ancestor', current, sha], repoAbs).ok;
|
|
85
|
+
if (!currentIsAncestor) targetIsAncestor = git.git(['merge-base', '--is-ancestor', sha, current], repoAbs).ok;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const d = decideMove({ channel, current, target: sha, label, currentIsAncestor, targetIsAncestor });
|
|
89
|
+
if (d.action === 'refuse') return { channel, ok: false, ...d };
|
|
90
|
+
if (d.action === 'noop' || dry) return { channel, ok: true, ...d, ...(dry && d.action !== 'noop' ? { detail: `[--dry] would be: ${d.detail}` } : {}) };
|
|
91
|
+
|
|
92
|
+
// No --force, no lease: git itself refuses a non-fast-forward, so a channel moved meanwhile is
|
|
93
|
+
// refused here too rather than overwritten.
|
|
94
|
+
const push = git.run('git', ['push', remote, `${sha}:refs/heads/${channel}`], { cwd: repoAbs, env: { ...env, [RELEASE_ENV]: '1' } });
|
|
95
|
+
if (!push.ok) return fail(`${channel} NOT moved: git push ${remote} ${short(sha)}:refs/heads/${channel} failed (${(push.stderr || '').split('\n').filter(Boolean).pop() || push.code})`);
|
|
96
|
+
return { channel, ok: true, ...d };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { CHANNELS, RELEASE_ENV, decideMove, moveChannel };
|
package/tools/lib/stamp.js
CHANGED
|
@@ -86,6 +86,43 @@ function packageVersion(root) {
|
|
|
86
86
|
}
|
|
87
87
|
}
|
|
88
88
|
|
|
89
|
+
/** The npm name this CLI publishes under — must equal the root package.json's `name` (a test pins it). */
|
|
90
|
+
const PACKAGE_NAME = '@futurelastic/colab-handbook';
|
|
91
|
+
|
|
92
|
+
/** True when `root` is its own git checkout — the toplevel git finds IS `root`, not an enclosing repo. */
|
|
93
|
+
function ownsGit(root) {
|
|
94
|
+
const top = gitIn(root, ['rev-parse', '--show-toplevel']);
|
|
95
|
+
return top.ok && realPath(top.out) === realPath(require('path').resolve(root));
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* `{ root, version }` when `root` is THIS CLI installed from the npm registry, else null (#444).
|
|
100
|
+
*
|
|
101
|
+
* Three conditions, all required:
|
|
102
|
+
* - no git of its own (an enclosing repo does not count — see handbookInfo);
|
|
103
|
+
* - `<root>/package.json` names this package, so an unrelated package.json never qualifies;
|
|
104
|
+
* - `root` sits under a `node_modules/` directory. Without this, a handbook working tree that is
|
|
105
|
+
* file-synced to another machine with its `.git` deliberately left behind would pass the first
|
|
106
|
+
* two and be reported as a registry install. npx, `npm i` and `npm i -g` all install there.
|
|
107
|
+
*
|
|
108
|
+
* `version` is package.json's verbatim — a candidate's `1.12.0-rc.8` included. That is the point:
|
|
109
|
+
* this answers "which build is running", where handbookInfo answers "what may I stamp with", and a
|
|
110
|
+
* candidate is never the latter (#334) — so its stricter packageVersion is right for it, wrong here.
|
|
111
|
+
*/
|
|
112
|
+
function npmPackageInfo(root) {
|
|
113
|
+
const p = require('path');
|
|
114
|
+
if (!p.resolve(root).split(p.sep).includes('node_modules')) return null;
|
|
115
|
+
let j;
|
|
116
|
+
try {
|
|
117
|
+
j = JSON.parse(require('fs').readFileSync(p.join(root, 'package.json'), 'utf8'));
|
|
118
|
+
} catch (_) {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
if (!j || j.name !== PACKAGE_NAME || typeof j.version !== 'string' || !j.version) return null;
|
|
122
|
+
if (ownsGit(root)) return null;
|
|
123
|
+
return { root, version: j.version };
|
|
124
|
+
}
|
|
125
|
+
|
|
89
126
|
/**
|
|
90
127
|
* The handbook's own identity: { root, hasGit, untagged, version }.
|
|
91
128
|
* Before the first tag exists the version is 'v0' and `untagged` is true, which DEACTIVATES stamp
|
|
@@ -693,7 +730,7 @@ module.exports = {
|
|
|
693
730
|
FROZEN_STAMP_NAME, FROZEN_STAMP_FILE, FROZEN_SOURCES, classifyFrozen,
|
|
694
731
|
AUTHORITY_FLIP_VERSION,
|
|
695
732
|
gitIn, gitCommonDir, isHandbookItself,
|
|
696
|
-
handbookInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
|
|
733
|
+
handbookInfo, PACKAGE_NAME, npmPackageInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
|
|
697
734
|
AXES, axesPredating,
|
|
698
735
|
WRITES_VETO_MARKER, writesRulingKnownAt,
|
|
699
736
|
stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,
|