diff --git a/skills/github-release/SKILL.md b/skills/github-release/SKILL.md index ddf3932..0300313 100644 --- a/skills/github-release/SKILL.md +++ b/skills/github-release/SKILL.md @@ -20,6 +20,8 @@ These commands are blocked by hooks. GitHub immutable releases (GA Oct 2025) mak **`gh release edit` is allowed ONLY for `--notes` / `--notes-file`** to overhaul the release description after CI publishes. All other `gh release edit` flags are blocked. +**No editorializing** in release notes, PR/commit text and docs — state what a release does, not how good the work is; no self-praise or narrating the expected. See `references/no-editorializing.md`. + ## Release Flow 1. **Detect ecosystem** — identify version files for the project type (see `references/ecosystem-detection.md`) @@ -27,11 +29,11 @@ These commands are blocked by hooks. GitHub immutable releases (GA Oct 2025) mak 3. **Bump version files** — update all ecosystem-specific version files consistently 4. **Update CHANGELOG.md** — add release section with date and changes 5. **Create release branch and PR** — `release/vX.Y.Z` branch, open PR for review (always use a PR — branch protection typically blocks direct pushes) -6. **After PR merge** — `git checkout main && git pull`, assert HEAD equals the fetched remote tip (stale-worktree guard; abort on mismatch), then tag `main`'s HEAD, never the `release/vX.Y.Z` branch tip: `git tag -s vX.Y.Z -m "vX.Y.Z"` — see `references/release-process.md` Phase 3. +6. **After PR merge** — `git checkout main && git pull`, assert HEAD equals the remote tip (stale-worktree guard), then tag `main`'s HEAD (never the `release/vX.Y.Z` tip): `git tag -s vX.Y.Z -m "vX.Y.Z"` — see `references/release-process.md` Phase 3. 7. **Push tag** — `git push origin vX.Y.Z` triggers CI workflow 8. **CI publishes release** — with artifacts, checksums, and auto-generated release notes 9. **Overhaul release description** — rewrite auto-generated notes into a narrative summary; add a **Contributors** section crediting code authors + issue reporters (bots filtered) via `scripts/harvest-contributors.sh`; apply with `gh release edit vX.Y.Z --notes-file notes.md` -10. **Do NOT re-run the release workflow after step 9** — many workflows (e.g. `softprops/action-gh-release`) regenerate the body each run and will overwrite the overhaul. For downstream retries (TER publish, artifact upload), use a dedicated dispatcher workflow — see `references/ter-republish.md`. +10. **Do NOT re-run the release workflow after step 9** — many workflows regenerate the body each run and overwrite the overhaul. For downstream retries, use a dedicated dispatcher — see `references/ter-republish.md`. ## Commands @@ -46,11 +48,12 @@ These commands are blocked by hooks. GitHub immutable releases (GA Oct 2025) mak ## References -- `references/release-process.md` — complete flow documentation -- `references/ecosystem-detection.md` — version file patterns per ecosystem -- `references/immutable-releases.md` — GitHub immutable releases and tag burning -- `references/supply-chain-security.md` — SLSA, Sigstore, SBOMs, attestations -- `references/recovery-procedures.md` — burned tags, stuck drafts, version drift, release-body clobbering, branch-protection gotchas -- `references/ter-republish.md` — TYPO3 TER re-publish patterns -- `references/typo3-ter-publishing.md` — TYPO3 initial-publish gotchas (tag/`ext_emconf.php` version match, `v`-prefix handling) -- `references/ci-workflow-templates.md` — CI workflow structure and templates +- `references/release-process.md` +- `references/ecosystem-detection.md` — version-file patterns +- `references/immutable-releases.md` — immutable releases, tag burning +- `references/supply-chain-security.md` — SLSA, Sigstore +- `references/recovery-procedures.md` — burned tags, stuck drafts, drift, body clobbering +- `references/ter-republish.md` — TER re-publish +- `references/typo3-ter-publishing.md` — TYPO3 initial-publish gotchas +- `references/ci-workflow-templates.md` — CI workflow templates +- `references/no-editorializing.md` — no self-praise diff --git a/skills/github-release/references/no-editorializing.md b/skills/github-release/references/no-editorializing.md new file mode 100644 index 0000000..f6cf3e0 --- /dev/null +++ b/skills/github-release/references/no-editorializing.md @@ -0,0 +1,41 @@ +# No editorializing — inform, don't sell (tone, not wordlist) + +Applies to every written artifact: commit messages, PR/MR descriptions, review +comments, issue/ticket text, chat — and code comments, docstrings, +documentation, README and changelog files. + +Editorializing is a matter of **tone and intent, not specific words** — no +banned-word list catches it, and the same word can be fine or not depending on +whether it carries a fact. The failure is writing about *how good, clean, or +careful the work is* instead of *what it does*. The reader has the diff and the +artifact; anything that only flatters the work or reassures them adds nothing, +and to a reviewer it reads as salesmanship — it provokes a counter-reaction +before they reach the substance. + +Apply three tests before a sentence stays: + +1. **Deletion** — remove the phrase. Did the reader lose a fact? If not, cut it. +2. **Subject** — is the sentence about the change, or about *you / your work* + (its quality, your diligence)? The latter goes. +3. **Voice** — would a terse maintainer write this, or does it read like a + cover letter? + +Two recurring failure modes: + +- **Announcing the expected.** Passing tests, clean linters, "documented", "no + regressions", "works as expected" are the baseline — do not narrate them. + State a check's status only to flag an *exception* (something knowingly + failing or skipped). In a test/verification list, say what was *added or + covered*, not that it is green. + +- **Self-praise and reassurance.** Grading your own output ("clean", "robust", + "elegant", "foolproof", "tidy", "genuinely new", "production-ready"); framings + that reassure ("the honest breaking change", "deliberately scoped, not + hidden", "where it belongs"); and the diligence humble-brag ("I carefully…", + "I made sure to…", "thoroughly tested"). These describe the author, not the + change. Show the fact; drop the framing. (The words are only symptoms — judge + by the three tests above, not by the word.) + +Use plain labels, not graded ones: "Breaking change", "Tests", "Limitations" — +not "Tests (all green)" or "Breaking change (honest)". If a limitation's cause +matters, it is already stated in the item.