From 77bd53f3584260d03e6b9307b4ec5861938043d4 Mon Sep 17 00:00:00 2001 From: Robin Bowes Date: Wed, 11 Nov 2026 17:25:10 +0000 Subject: [PATCH] docs: record the commitlint trailer decision and release knowledge Adds the decision behind #22 (the footer length rule skips Co-authored-by lines), amends the release decision with the arm64 published-image check from #21, and adds a knowledge index with how a release is cut and what a healthy run logs. Co-Authored-By: Claude Opus 5.5 --- ...1-commitlint-ignores-co-author-trailers.md | 40 +++++++++++++++++++ ...release-please-pins-image-on-release-pr.md | 9 ++++- knowledge/INDEX.md | 18 +++++++++ knowledge/releases/knowledge.md | 35 ++++++++++++++++ 4 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 decisions/2026-11-11-commitlint-ignores-co-author-trailers.md create mode 100644 knowledge/INDEX.md create mode 100644 knowledge/releases/knowledge.md diff --git a/decisions/2026-11-11-commitlint-ignores-co-author-trailers.md b/decisions/2026-11-11-commitlint-ignores-co-author-trailers.md new file mode 100644 index 00000000..742040d1 --- /dev/null +++ b/decisions/2026-11-11-commitlint-ignores-co-author-trailers.md @@ -0,0 +1,40 @@ +## Decision: this repository's commitlint footer length rule skips `Co-authored-by` lines + +`commitlint.config.mjs` turns off `footer-max-line-length` and replaces it with +`function-rules/footer-max-line-length`, which drops `Co-authored-by:` lines (case-insensitive) +from the footer and applies the 100-character limit to what remains (#22). + +## Context: Commitlint failed on `main` for both release commits + +v7.0.0 (`aab35a7`) and v7.1.0 (`8008080`) each failed the Commitlint workflow's push run on +`main` with `footer-max-line-length`. A release PR holds the pin commit, written by the +`semantic-release-pusher` App, so its squash commit gains a `Co-authored-by` trailer for the App +whose noreply address, `283137246+semantic-release-pusher[bot]@users.noreply.github.com`, makes +the line 110 characters. The PR's own checks lint its commits one by one and never see that +trailer. The v7.0.0 failure went unnoticed until v7.1.0 because only the Release workflow was +watched. + +## Alternatives considered: + +- **Raise the footer limit for everything.** Would let long `Refs:` or `BREAKING CHANGE:` lines + through too; only the trailer is outside an author's control. +- **Squash with `PR_BODY` or `BLANK` instead of `COMMIT_MESSAGES`.** `COMMIT_MESSAGES` is the + default for every repository in `yo61/github-repos` (`modules/github-repo/variables.tf`), and + the release PR body is release-please's changelog, not a fit for a commit body. +- **Lint only pull requests, not pushes to `main`.** The push run is also the job that runs the + action against its own history; dropping it to avoid one rule loses that. +- **Write the pin commit with `GITHUB_TOKEN`.** Its commits start no workflows, so the release PR + would not run CI on the pinned image. + +## Reasoning: + +The trailer's length comes from the App's noreply address, which no author can shorten, so the +exemption is narrow and permanent. It follows the existing `function-rules/body-max-line-length` +rule beside it, which already exempts dependency-bump bodies the same way. + +## Trade-offs accepted: + +- A hand-written `Co-authored-by` line of any length passes. +- The two failed runs on `main` stay red; their commits are history. + +## Supersedes: none diff --git a/decisions/2026-11-11-release-please-pins-image-on-release-pr.md b/decisions/2026-11-11-release-please-pins-image-on-release-pr.md index adfd669b..f6c9c075 100644 --- a/decisions/2026-11-11-release-please-pins-image-on-release-pr.md +++ b/decisions/2026-11-11-release-please-pins-image-on-release-pr.md @@ -21,8 +21,8 @@ removed. ## Alternatives considered: -- **Pin by tag again** (`image: docker://…:X.Y.Z`, bumped by an `x-release-please-version` marker). - Simplest, but reverses `fae6c5c`: a tag can be repointed after release. +- **Pin by tag again** (`image: docker://…:X.Y.Z`, bumped by an `x-release-please-version` + marker). Simplest, but reverses `fae6c5c`: a tag can be repointed after release. - **Release first, pin after.** Leave the build on the tag and have a bot PR pin the digest. Every release would ship the previous release's image. - **Build from the Dockerfile at run time** (`image: Dockerfile`), as upstream once did. No pin to @@ -80,4 +80,9 @@ architecture's revision label against the release commit, and smoke tests it nat then checks the index holds exactly both platforms, tags it, and confirms each tag resolves to the pinned digest. +First shipped in v7.1.0 (#19, #20). Once `main` pinned the two-platform index, +`commitlint-from-published-image` gained an `ubuntu-24.04-arm` leg (#21), so every PR, the release +PR included, runs the pinned image as consumers do on both architectures. A release PR pinning an +amd64-only image fails that leg before anything is tagged. + ## Supersedes: none diff --git a/knowledge/INDEX.md b/knowledge/INDEX.md new file mode 100644 index 00000000..6ca88eab --- /dev/null +++ b/knowledge/INDEX.md @@ -0,0 +1,18 @@ +# Knowledge index + +Routes to this repository's knowledge folders. Each domain holds `knowledge.md` (facts and +patterns) and, when there are any, `hypotheses.md` (need more data) and `rules.md` (confirmed +three or more times; apply by default). Knowledge that spans repositories is in `yo61/global`'s +`knowledge/`. + +- [releases](releases/knowledge.md) — cutting a release with release-please and the pinned + multi-arch image, and what a healthy run logs. + +## Decisions + +Decisions live in [`../decisions/`](../decisions/). + +- `2026-11-11-release-please-pins-image-on-release-pr.md` — release-please builds the image on the + release PR and pins its digest there; amended the same day for linux/arm64. +- `2026-11-11-commitlint-ignores-co-author-trailers.md` — the footer length rule skips + `Co-authored-by` lines, which release commits gain from the App. diff --git a/knowledge/releases/knowledge.md b/knowledge/releases/knowledge.md new file mode 100644 index 00000000..2b02ad65 --- /dev/null +++ b/knowledge/releases/knowledge.md @@ -0,0 +1,35 @@ +# Releases — knowledge (facts and patterns) + +How a release of this action goes, as run for v7.0.0 and v7.1.0 on 2026-11-11. The design is in +[the decision record](../../decisions/2026-11-11-release-please-pins-image-on-release-pr.md). +Patterns shared with other repositories are in `yo61/global`'s `knowledge/releases/`. + +## Cutting a release + +1. A releasable commit (`feat`, `fix`, `perf`, `deps`, `revert`, `docs`, `refactor`, `build`) + lands on `main`. `ci`, `chore`, `test` and `style` do not open a release PR. +2. The Release run opens or updates "chore(main): release X.Y.Z". In the same run `pin-prepare`, + the `pin-build` matrix and `pin-commit` add `chore(release): pin image digest <12 hex>` on top. +3. Merge the release PR only when that pin commit is its newest commit and CI is green. Merged + earlier, `verify` refuses to tag and the version is left without an image; release a patch. +4. On the merge commit, check every workflow, not just Release: Release, CI and Commitlint all run + on it, and it is the one commit no PR check has seen. +5. `verify` logs, per architecture, `… (x86_64|aarch64) was built from , the released + source` and the Node and commitlint versions; `publish` logs `tagged … as X.Y.Z and X` and + `vX now points at `. + +## What healthy looks like + +- release-please logs a small `Considering: N commits` (2 after v7.0.0). The whole history means + it lost its anchor on the latest GitHub Release. +- With no release PR open, `pin-prepare` logs `no open release PR; nothing to pin`. +- `ghcr.io/yo61/commitlint-github-action:X.Y.Z`, `:X` and the digest in `action.yml` on `main` + are one index holding `linux/amd64` and `linux/arm64`, whose revision labels both name the + release PR's release-please commit. + +## Checking an image from a Mac + +The image has no `darwin` variant; pass `--platform linux/amd64` or `linux/arm64` to +`docker pull` and `docker run`. To read an index without pulling: +`docker buildx imagetools inspect --format '{{json .Manifest}}'` (digest, platforms) and +`--format '{{json .Image}}'` (per-platform config, labels).