Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions decisions/2026-11-11-commitlint-ignores-co-author-trailers.md
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
18 changes: 18 additions & 0 deletions knowledge/INDEX.md
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 35 additions & 0 deletions knowledge/releases/knowledge.md
Original file line number Diff line number Diff line change
@@ -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 <sha>, the released
source` and the Node and commitlint versions; `publish` logs `tagged … as X.Y.Z and X` and
`vX now points at <sha>`.

## 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 <ref> --format '{{json .Manifest}}'` (digest, platforms) and
`--format '{{json .Image}}'` (per-platform config, labels).
Loading