diff --git a/Forge-and-Tooling.md b/Forge-and-Tooling.md index bfe8d55..e224a7f 100644 --- a/Forge-and-Tooling.md +++ b/Forge-and-Tooling.md @@ -72,6 +72,20 @@ git log --show-signature -1 # the long form If signing fails, stop and report. Pushing unsigned work only moves the failure to a place where it costs a review. +### The same setting makes a lightweight tag impossible + +`tag.gpgsign = true` comes with it, and it forces every tag into the annotated form. **`git tag ` therefore cannot create a lightweight tag here** — it aborts with `fatal: no tag message?`. + +That matters where a tag series is expected to be uniform. `workflow-util/pipelines` versions its shared building blocks with lightweight tags (`v1`, `v2`, `v3`), and a mixed series is an inconsistency nobody can explain a year later. The way through: + +```bash +git update-ref refs/tags/ +git push origin refs/tags/ +git cat-file -t # must print "commit", not "tag" +``` + +`cat-file -t` is the check, not the assumption: a lightweight tag points straight at the commit, an annotated one at a tag object. `ls-remote --tags` shows the same difference — an annotated tag adds a second line ending in `^{}`. Measured on 2026-10-01 while tagging `v3` in that repository. + ## No merge queue — auto-merge takes its place Gitea has no merge queue. Its place is taken by **auto-merge on green checks**: a PR is armed once and merges itself when the required check passes **and the required review exists**. Both are active on `main` — an armed PR that nobody has reviewed sits there instead of merging, which is what makes Renovate's global `platformAutomerge: true` something other than unattended merging (see [Renovate → PR policy](Renovate#pr-policy)). diff --git a/Lessons-Learned.md b/Lessons-Learned.md index 569304f..1f59f54 100644 --- a/Lessons-Learned.md +++ b/Lessons-Learned.md @@ -210,6 +210,16 @@ That is exactly the problem. **The cost is not in the version you verified; it i **Now:** the obligation is written **at the `command:` line in the StatefulSet**, not only in the chart page and not only in the pull request — re-read the upstream `entrypoint.sh` at every app-version update, and if it has grown beyond uid/gid handling, stop. Generally: **overriding a container's entrypoint forks it silently, and a fork with no diff is a fork nobody reviews.** The mitigation for a decision whose risk is entirely in the future is to leave the instruction where the future change will be made, not where the decision was argued. +## The file that moved, and the comments that kept vouching for it + +Moving `publish-helm-chart.yml` out to `workflow-util/pipelines` left three references behind in this repository, and the sharpest of them was a comment in `install-test.yml` that cited the departed file as documenting a trap **"at length"**. + +That comment still reads as a complete justification. Nothing about it looks broken: it is grammatical, it is specific, and it points at a long explanation — which is now in a different repository, where nobody following the comment will look. The README had the same shape in its "runs in five places" list, naming a file that no longer existed here, and `CLAUDE.md` still called the workflow ours. + +**A moved file does not make its inbound references stale. It makes them false** — and a false reference is worse than a missing one, because it answers the question instead of raising it. + +**Now:** before a file leaves the repository, grep for its name across the whole tree, **comments included**, not only the `uses:` and `include` lines that a tool would find. All three cases here came out of that one grep, and none of them was in the diff the move itself produced. + ## The recurring shape - **Green is a claim about the assertions that ran, not about the system.** @@ -220,4 +230,5 @@ That is exactly the problem. **The cost is not in the version you verified; it i - **Write down what was measured, and say when something was not.** Half of this page exists because someone recorded a number instead of an impression. - **A document handed to you as context is a copy, not the source.** Correcting the file does not correct the copies already delivered, and a stale copy looks exactly as authoritative as a current one — only the file itself, and its diff against `origin/main`, settle what a rule says. - **Put the warning where the next change will be made.** A risk that only materializes at the next upgrade belongs at the line that upgrade will touch — a note in the pull request that argued the decision is read once, by people who already know. +- **A reference to something that moved is false, not stale.** It still answers the question, which is why nobody re-asks it — so a file leaving the repository is a grep across the whole tree, comments included, not only the lines a tool can resolve. - **An answer that arrived by accident is worth making repeatable.** The all-charts install-test exists because one unplanned run produced a result nobody could have asked for; the fix is a way to ask the question on purpose, not a note to remember the accident.