diff --git a/skills/kvb-release-changelog/SKILL.md b/skills/kvb-release-changelog/SKILL.md index e9a5bfa..64cc267 100644 --- a/skills/kvb-release-changelog/SKILL.md +++ b/skills/kvb-release-changelog/SKILL.md @@ -6,7 +6,7 @@ description: > markdown-lint rejection. --- -Read `reasons.md` next to this file when a rule seems not to fit or a lint +Read `reasons.md` next to this file when a rule does not fit or a lint finding is unclear, and `special.md` for: no tag, a failed previous-tag workflow, a test- or CI-only release, no `markdownlint-cli2`, a pasted pkgmgr rejection. @@ -35,8 +35,9 @@ git log --no-merges --format='%h %s%n%b' ..HEAD Fixed. `!` or `BREAKING CHANGE:`: Breaking, plus one Upgrade notes line per required action. `docs`, `style`, `refactor`, `test`, `ci`, `build`, `chore`: omitted unless a user sees the effect. Dependency bumps: one -collapsed line, or omitted. Order: Breaking, Added, Changed, Fixed, Upgrade -notes; empty sections left out. +line, or omitted. Order: Breaking, Added, Changed, Fixed, Version +jumps, Upgrade notes, Contributors (always, with URLs: `sections.md`); +empty sections left out. ## 3. Format @@ -44,7 +45,7 @@ notes; empty sections left out. bold-only lines. 2. No version heading, date or "Release X.Y.Z" line. 3. One bullet, one line: too long means shorter, never wrapped. -4. Line length: the repository's MD013 limit (markdownlint's default 80); +4. Line length: the repository's MD013 limit (default 80); aim for 78 or less. 5. Lists: no nesting, a blank line before and after (MD004, MD032), the marker of the existing CHANGELOG.md's first list item; `-` without a diff --git a/skills/kvb-release-changelog/sections.md b/skills/kvb-release-changelog/sections.md new file mode 100644 index 0000000..0d817ec --- /dev/null +++ b/skills/kvb-release-changelog/sections.md @@ -0,0 +1,63 @@ +# Version jumps, Contributors and net counting + +## Net, not per commit + +After a long-lived branch merges, `git log ..HEAD` lists commits that +were already released under other SHAs (v16.2.3..main held 2430 commits; the +Wazuh role shipped in 16.1.0 and reappeared through the store-i18n merge). +Judge every Added, Changed and Fixed line against `git diff ..HEAD` and +the earlier CHANGELOG.md entries, never against the commit list alone. + +## Version jumps (net since X.Y.Z) + +Only in a repository that pins a version per role +(`roles/*/meta/services.yml`): one `- *role*: old to new` line per role whose +pinned version differs between the tag and HEAD: + +```bash +git diff ..HEAD -- 'roles/*/meta/services.yml' +``` + +Compare the `version` field of every entity in each file at both refs: a +version bumped twice shows once, one changed and changed back not at all. +The same comparison covers every other pin: + +- `ref` and `*_version` keys beside `version` (a pkgmgr `ref`, a + `webui_version`, a `builder_version`). +- Add-on pins in `roles/*/meta/addons/*.yml`. +- Renamed or split roles: pair the old and the new role (`git diff -M + --name-status ..HEAD -- roles/`) before comparing, else the jump + hides behind the rename. A rename without an alias is also a Breaking + line plus an Upgrade note. +- Manifests outside the roles: `requirements/requirements.galaxy.yml` + collections and the `pyproject.toml` pins. + +A change that is no version bump (an image swapped for a source build, a +base like `cpu` becoming `22.04`, `2026.8.0` becoming `3.13`) needs +judgement: a Changed line or an Upgrade note, never a jump line. + +## Contributors + +Always, one `- [Name](URL): areas` line per human author and +`Co-authored-by` trailer in the range, the areas taken from that person's +commits: + +```bash +git log --format='%aN%n%(trailers:key=Co-authored-by,valueonly)' ..HEAD +git check-mailmap ' ' +``` + +- Names go through `.mailmap`, so one person shows once. +- Bots stay out: dependabot, updaters, github-actions, Claude and other AI + co-authors. +- The URL comes from earlier entries (CHANGELOG.md, + `packaging/debian/changelog`); `.mailmap` holds none. A person without one + there is asked for, never left without a URL. + +Example: + +```text +Contributors: + +- [Kevin Veen-Birkenbach](https://veen.world): PHP hardening, Node.js +```