@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13790 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# Release (tag) — TEMPLATE. Copy me into your repo at .github/workflows/release.yml.
|
|
2
|
+
#
|
|
3
|
+
# This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
|
|
4
|
+
# Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
|
|
5
|
+
# calls this file remotely and nothing will update it for you — divergence between
|
|
6
|
+
# your copy and the handbook is expected and fine. If you find an improvement worth
|
|
7
|
+
# sharing, change the handbook template too, but that is a manual, deliberate act.
|
|
8
|
+
#
|
|
9
|
+
# EDIT POINTS are marked `# EDIT:` — walk them once after copying.
|
|
10
|
+
#
|
|
11
|
+
# TIER A ONLY. Under the tiered branch model, a Tier A release is: merge dev -> main,
|
|
12
|
+
# heavy CI on main goes green, tag v*.*.*. The tag is what triggers deployment. This
|
|
13
|
+
# workflow runs alongside that deploy and produces the human-facing record of the release.
|
|
14
|
+
#
|
|
15
|
+
# Do NOT copy this into a Tier C repo. Tier C has no tag step — promotion dev -> main
|
|
16
|
+
# IS the deploy — so this workflow would never fire. Tier B has no production at all.
|
|
17
|
+
#
|
|
18
|
+
# It publishes a GitHub Release whose body is:
|
|
19
|
+
# 1. A hand-readable summary WE build — commits since the previous tag, grouped by
|
|
20
|
+
# Conventional Commit type (feat / fix / perf / docs / chore / other).
|
|
21
|
+
# 2. GitHub's own generated notes, appended below by generate_release_notes: true.
|
|
22
|
+
#
|
|
23
|
+
# Why both: the generated notes are PR-centric and list every merge flatly, which is
|
|
24
|
+
# noise when a release contains thirty commits. The grouped summary answers "what
|
|
25
|
+
# actually changed" at a glance; the generated notes stay for full traceability.
|
|
26
|
+
#
|
|
27
|
+
# PRE-RELEASE TAGS (release candidates, `vX.Y.Z-rc.N`). This workflow fires on them —
|
|
28
|
+
# GitHub's `*` matches `-` and `.`, so the `v*.*.*` trigger below matches `v1.3.0-rc.1`
|
|
29
|
+
# as well as `v1.3.0`. That is deliberate HERE: a candidate deserves a record too. What
|
|
30
|
+
# it must not do is pass for a final release, so both decisions come from the tag NAME,
|
|
31
|
+
# never from a constant:
|
|
32
|
+
#
|
|
33
|
+
# tag GitHub Release summary diffs against
|
|
34
|
+
# ------------- -------------------- -------------------------------------------------
|
|
35
|
+
# v1.3.0-rc.1 pre-release the previous FINAL tag (e.g. v1.2.1) — never
|
|
36
|
+
# an earlier candidate, so rc.2 also lists
|
|
37
|
+
# everything since v1.2.1
|
|
38
|
+
# v1.3.0 full release the previous FINAL tag (e.g. v1.2.1) — NOT
|
|
39
|
+
# v1.3.0-rc.1, which would list almost nothing
|
|
40
|
+
#
|
|
41
|
+
# "Pre-release" = the tag name contains a `-` (SemVer §9). "Previous final" = the nearest
|
|
42
|
+
# `v*.*.*` tag reachable from the tag's parent whose name contains no `-`. None → the
|
|
43
|
+
# summary covers all history, candidate or final alike.
|
|
44
|
+
#
|
|
45
|
+
# ⚠ YOUR DEPLOY WORKFLOW MUST NOT FIRE ON A CANDIDATE. The same `*` rule means a deploy
|
|
46
|
+
# triggered on `v*.*.*` (or `v*`) deploys `v1.3.0-rc.1` to production — the first
|
|
47
|
+
# candidate anyone cuts ships. Exclude pre-releases explicitly in deploy-*.yml; a `!`
|
|
48
|
+
# pattern only removes what an EARLIER positive pattern in the same list matched:
|
|
49
|
+
#
|
|
50
|
+
# on:
|
|
51
|
+
# push:
|
|
52
|
+
# tags:
|
|
53
|
+
# - "v*.*.*" # every version tag…
|
|
54
|
+
# - "!v*.*.*-*" # …except a pre-release (v1.3.0-rc.1, v2.0.0-beta.2)
|
|
55
|
+
#
|
|
56
|
+
# NO TOOLCHAIN RESOLUTION HERE. This workflow installs neither Node nor PHP — it is
|
|
57
|
+
# git plus shell. There is no version to resolve, so there is nothing to declare.
|
|
58
|
+
#
|
|
59
|
+
# DEPLOYMENT DOES NOT BELONG HERE. Deploy workflows are repo-specific (SSH host, app
|
|
60
|
+
# dir, docroot symlink, migration reconcile) and ours must run on the JP self-hosted
|
|
61
|
+
# runner because XServer blocks non-JP IPs on SSH (海外アクセス制限). Keep deploy-*.yml
|
|
62
|
+
# as its own file.
|
|
63
|
+
|
|
64
|
+
name: Release
|
|
65
|
+
|
|
66
|
+
on:
|
|
67
|
+
push:
|
|
68
|
+
tags:
|
|
69
|
+
# EDIT: only if this repo uses a different tag shape. This pattern matches
|
|
70
|
+
# pre-release tags too (v1.3.0-rc.1) ON PURPOSE — see "PRE-RELEASE TAGS" above:
|
|
71
|
+
# a candidate gets a pre-release record here. A DEPLOY workflow must never copy
|
|
72
|
+
# this list as-is; it needs the "!v*.*.*-*" exclusion shown in the header.
|
|
73
|
+
- "v*.*.*"
|
|
74
|
+
|
|
75
|
+
env:
|
|
76
|
+
# Attach build artifacts to the release.
|
|
77
|
+
#
|
|
78
|
+
# NOTE, and this differs from a reusable workflow: a tag push is its OWN run. There
|
|
79
|
+
# is no artifact lying around from the CI run on main. To use this you must add a
|
|
80
|
+
# build job to THIS file that uploads an artifact, and make the release job
|
|
81
|
+
# `needs:` it. Left false because most of our repos build on the deploy target.
|
|
82
|
+
ATTACH_ARTIFACTS: "false"
|
|
83
|
+
# Empty means every artifact from this run.
|
|
84
|
+
ARTIFACT_NAME: ""
|
|
85
|
+
# EDIT: "true" to publish as a draft so a human edits before it goes out.
|
|
86
|
+
RELEASE_DRAFT: "false"
|
|
87
|
+
# No RELEASE_PRERELEASE constant, on purpose: a fixed "false" published a candidate
|
|
88
|
+
# tag as a full release. Pre-release is derived from the tag name in the step below.
|
|
89
|
+
|
|
90
|
+
jobs:
|
|
91
|
+
release:
|
|
92
|
+
name: Publish release
|
|
93
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
94
|
+
permissions:
|
|
95
|
+
# Required to create the release. Nothing else is needed — keep it minimal.
|
|
96
|
+
contents: write
|
|
97
|
+
steps:
|
|
98
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
99
|
+
with:
|
|
100
|
+
# Full history plus tags: the summary is a diff between this tag and the
|
|
101
|
+
# previous one, which is impossible on a shallow clone.
|
|
102
|
+
fetch-depth: 0
|
|
103
|
+
persist-credentials: false
|
|
104
|
+
|
|
105
|
+
- name: Resolve tag and previous tag
|
|
106
|
+
id: tags
|
|
107
|
+
run: |
|
|
108
|
+
set -euo pipefail
|
|
109
|
+
TAG="${GITHUB_REF_NAME}"
|
|
110
|
+
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
|
|
111
|
+
|
|
112
|
+
# Pre-release = the tag name carries a SemVer pre-release suffix (`-rc.1`,
|
|
113
|
+
# `-beta.2`). Derived from the name, never a constant.
|
|
114
|
+
case "$TAG" in
|
|
115
|
+
*-*) PRERELEASE=true ;;
|
|
116
|
+
*) PRERELEASE=false ;;
|
|
117
|
+
esac
|
|
118
|
+
echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
|
|
119
|
+
|
|
120
|
+
# Previous tag = nearest v*.*.* tag reachable from this tag's parent that is
|
|
121
|
+
# NOT itself a pre-release — for a candidate and a final alike. Without the
|
|
122
|
+
# --exclude, `v*.*.*` matches `v1.3.0-rc.1`, and the final v1.3.0's summary
|
|
123
|
+
# would diff against its own candidate and list almost nothing. Empty when no
|
|
124
|
+
# earlier final exists (first release).
|
|
125
|
+
PREV="$(git describe --tags --abbrev=0 --match 'v*.*.*' --exclude '*-*' "${TAG}^" 2>/dev/null || true)"
|
|
126
|
+
echo "prev=$PREV" >> "$GITHUB_OUTPUT"
|
|
127
|
+
|
|
128
|
+
KIND="Release"
|
|
129
|
+
[ "$PRERELEASE" = true ] && KIND="Pre-release"
|
|
130
|
+
if [ -n "$PREV" ]; then
|
|
131
|
+
echo "range=${PREV}..${TAG}" >> "$GITHUB_OUTPUT"
|
|
132
|
+
echo "$KIND $TAG — comparing against previous final $PREV"
|
|
133
|
+
else
|
|
134
|
+
echo "range=$TAG" >> "$GITHUB_OUTPUT"
|
|
135
|
+
echo "$KIND $TAG — no earlier final tag, summarising all history"
|
|
136
|
+
fi
|
|
137
|
+
|
|
138
|
+
# MIRRORS the `colab release-notes` subcommand (tools/colab in this handbook). The two
|
|
139
|
+
# CANNOT share code — this workflow must stay copy-and-own self-contained (git + shell,
|
|
140
|
+
# no Node) — so they are deliberate duplicates of the same grouping logic. If you change
|
|
141
|
+
# the grouping or output format here, make the matching edit in tools/colab (and vice
|
|
142
|
+
# versa). `colab release-notes` exists so this summary can be built by hand when CI can't
|
|
143
|
+
# run (e.g. an org billing-lock on Actions). The mirror is the GROUPING; which tag is
|
|
144
|
+
# "previous" is decided in the step above, and a pre-release must never be it.
|
|
145
|
+
- name: Build grouped release summary
|
|
146
|
+
id: notes
|
|
147
|
+
env:
|
|
148
|
+
TAG: ${{ steps.tags.outputs.tag }}
|
|
149
|
+
PREV: ${{ steps.tags.outputs.prev }}
|
|
150
|
+
RANGE: ${{ steps.tags.outputs.range }}
|
|
151
|
+
run: |
|
|
152
|
+
set -euo pipefail
|
|
153
|
+
|
|
154
|
+
# Subject lines only, merge commits dropped — a merge subject carries no
|
|
155
|
+
# Conventional Commit meaning and would double-count its own commits.
|
|
156
|
+
git log --no-merges --pretty=format:'%s' "$RANGE" > /tmp/subjects.txt || true
|
|
157
|
+
# grep -c '' rather than wc -l: git log emits no trailing newline, so wc
|
|
158
|
+
# would undercount by one.
|
|
159
|
+
COUNT="$(grep -c '' /tmp/subjects.txt || true)"
|
|
160
|
+
COUNT="${COUNT:-0}"
|
|
161
|
+
|
|
162
|
+
emit_group() {
|
|
163
|
+
local type="$1" heading="$2"
|
|
164
|
+
# Matches 'feat: x', 'feat(scope): x', and the breaking-change 'feat!: x'.
|
|
165
|
+
local matched
|
|
166
|
+
matched="$(grep -E "^${type}(\([^)]*\))?!?:" /tmp/subjects.txt || true)"
|
|
167
|
+
[ -z "$matched" ] && return 0
|
|
168
|
+
printf '### %s\n\n' "$heading" >> /tmp/body.md
|
|
169
|
+
# Strip the type prefix; keep any scope as a bold lead-in.
|
|
170
|
+
printf '%s\n' "$matched" \
|
|
171
|
+
| sed -E "s/^${type}\(([^)]*)\)!?: */- **\1**: /; s/^${type}!?: */- /" \
|
|
172
|
+
>> /tmp/body.md
|
|
173
|
+
printf '\n' >> /tmp/body.md
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
: > /tmp/body.md
|
|
177
|
+
printf '## %s\n\n' "$TAG" >> /tmp/body.md
|
|
178
|
+
if [ -n "$PREV" ]; then
|
|
179
|
+
printf '%s commits since %s.\n\n' "$COUNT" "$PREV" >> /tmp/body.md
|
|
180
|
+
else
|
|
181
|
+
printf 'First release. %s commits.\n\n' "$COUNT" >> /tmp/body.md
|
|
182
|
+
fi
|
|
183
|
+
|
|
184
|
+
emit_group feat "Features"
|
|
185
|
+
emit_group fix "Fixes"
|
|
186
|
+
emit_group perf "Performance"
|
|
187
|
+
emit_group docs "Documentation"
|
|
188
|
+
emit_group chore "Chores"
|
|
189
|
+
|
|
190
|
+
# Anything that ignored the commit convention still has to appear, or the
|
|
191
|
+
# summary silently loses changes.
|
|
192
|
+
OTHER="$(grep -Ev '^(feat|fix|perf|docs|chore|refactor|test|build|ci|style)(\([^)]*\))?!?:' /tmp/subjects.txt || true)"
|
|
193
|
+
if [ -n "$OTHER" ]; then
|
|
194
|
+
printf '### Other\n\n' >> /tmp/body.md
|
|
195
|
+
printf '%s\n' "$OTHER" | sed -E 's/^/- /' >> /tmp/body.md
|
|
196
|
+
printf '\n' >> /tmp/body.md
|
|
197
|
+
fi
|
|
198
|
+
|
|
199
|
+
# Breaking changes deserve their own callout at the top of a reader's mind.
|
|
200
|
+
BREAKING="$(grep -E '^[a-z]+(\([^)]*\))?!:' /tmp/subjects.txt || true)"
|
|
201
|
+
if [ -n "$BREAKING" ]; then
|
|
202
|
+
printf '### Breaking changes\n\n' >> /tmp/body.md
|
|
203
|
+
printf '%s\n' "$BREAKING" | sed -E 's/^/- /' >> /tmp/body.md
|
|
204
|
+
printf '\n' >> /tmp/body.md
|
|
205
|
+
fi
|
|
206
|
+
|
|
207
|
+
printf -- '---\n\n' >> /tmp/body.md
|
|
208
|
+
|
|
209
|
+
echo "body-file=/tmp/body.md" >> "$GITHUB_OUTPUT"
|
|
210
|
+
|
|
211
|
+
# Same summary into the run page, so it is readable without opening Releases.
|
|
212
|
+
cat /tmp/body.md >> "$GITHUB_STEP_SUMMARY"
|
|
213
|
+
|
|
214
|
+
- name: Download build artifacts
|
|
215
|
+
if: env.ATTACH_ARTIFACTS == 'true'
|
|
216
|
+
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
|
217
|
+
with:
|
|
218
|
+
# Empty name = every artifact produced by this run.
|
|
219
|
+
name: ${{ env.ARTIFACT_NAME }}
|
|
220
|
+
path: release-artifacts
|
|
221
|
+
continue-on-error: true
|
|
222
|
+
|
|
223
|
+
- name: List artifacts to attach
|
|
224
|
+
if: env.ATTACH_ARTIFACTS == 'true'
|
|
225
|
+
run: |
|
|
226
|
+
if [ -d release-artifacts ] && [ -n "$(ls -A release-artifacts 2>/dev/null)" ]; then
|
|
227
|
+
find release-artifacts -type f | head -50
|
|
228
|
+
else
|
|
229
|
+
echo "::warning::ATTACH_ARTIFACTS is true but no artifacts were found. Publishing the release without files. Remember a tag push is its own run — add a build job to this file that uploads one."
|
|
230
|
+
fi
|
|
231
|
+
|
|
232
|
+
- name: Publish GitHub Release
|
|
233
|
+
uses: softprops/action-gh-release@v2
|
|
234
|
+
with:
|
|
235
|
+
tag_name: ${{ steps.tags.outputs.tag }}
|
|
236
|
+
name: ${{ steps.tags.outputs.tag }}
|
|
237
|
+
body_path: ${{ steps.notes.outputs.body-file }}
|
|
238
|
+
# Appends GitHub's own PR/contributor notes underneath our grouped summary.
|
|
239
|
+
generate_release_notes: true
|
|
240
|
+
draft: ${{ env.RELEASE_DRAFT == 'true' }}
|
|
241
|
+
# From the tag name (steps.tags) — a `-rc.N` tag is never published as a full,
|
|
242
|
+
# "Latest" release.
|
|
243
|
+
prerelease: ${{ steps.tags.outputs.prerelease == 'true' }}
|
|
244
|
+
files: ${{ env.ATTACH_ARTIFACTS == 'true' && 'release-artifacts/**/*' || '' }}
|
|
245
|
+
fail_on_unmatched_files: false
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<!-- Paste this into your repo's own CLAUDE.md. It is how an agent working in the repo
|
|
2
|
+
discovers the handbook — nothing else points here. Fill the <placeholders>.
|
|
3
|
+
Shape (CONVENTIONS.md §9 step 5): keep CLAUDE.md a thin shell — `@AGENTS.md` on its
|
|
4
|
+
first line, the repo's own prose in AGENTS.md — and keep THIS block in CLAUDE.md, not
|
|
5
|
+
AGENTS.md: the audit and `colab update` find the stamp here by name. No block belongs
|
|
6
|
+
in both files. `colab adopt` writes this shell on a new repo.
|
|
7
|
+
Set the stamp below to the handbook version you copied at (`colab template` prints
|
|
8
|
+
the current version, or run `git describe --tags` in the handbook). The audit reads
|
|
9
|
+
this stamp to tell you when the conventions have moved on since — keep it, don't
|
|
10
|
+
delete it. When you re-sync to a newer handbook, bump the version here. -->
|
|
11
|
+
|
|
12
|
+
## Conventions
|
|
13
|
+
|
|
14
|
+
<!-- colab-handbook @ <version> -->
|
|
15
|
+
|
|
16
|
+
This repo follows the [colab-handbook](https://github.com/futurelastic/colab-handbook/blob/main/CONVENTIONS.md) conventions.
|
|
17
|
+
|
|
18
|
+
- **Tier:** `<A|B|C>` — <A = a tag deploys · C = promotion dev→main deploys · B = no production target>
|
|
19
|
+
- **Trunk:** `<dev|main>` (feature branches `feat|fix|docs|chore|refactor|test|perf/<slug>`)
|
|
20
|
+
<!-- Tier A and C both use `dev`; only Tier B uses `main`. Delete this line after filling in. -->
|
|
21
|
+
- **Descriptor:** see `.github/project.yml`. CI workflows are copy-and-own from the handbook's `templates/` — this repo owns its copies, they are not called remotely.
|