Add frontmatter to the update-changelog skill and trim it down - #292
Conversation
There was a problem hiding this comment.
Thanks for this — the frontmatter is right (valid YAML, name matches the directory, and the trigger phrasings cover the realistic asks), and I checked the central claim rather than taking it on trust. I walked all 34 instructions, paths, commands and edge cases in the old file against the new one: the trim is faithful. Every item is preserved, reworded without changing behavior, or dropped deliberately, including all five Step 5 checklist constraints, which are each restated elsewhere in the new file. "The process itself is unchanged" holds for the trim, which is most of the diff.
It does not cover Step 1, which is new text rather than shortened text, and that is where the two warnings are. The merge-base --is-ancestor check cannot ever report "already released" for a commit taken from the range it is meant to filter — the two commands are complements by construction — and the topology it rests on is false for the four most recent tags. Neither is your invention; the wording comes from #281 and from cut-a-release in #278, and I will fix #278 on my side. But this PR is what lands it on main, so I would like it corrected here.
I'll handle the updates on my side.
2 warnings, 3 suggestions, 2 nitpicks. No critical findings.
🤖 AI-assisted comment, reviewed and approved by @medley56 before posting.
The skill had no YAML frontmatter, so Claude Code could not discover it. Add `name` and a `description` carrying the trigger conditions, and cut the file from ~110 to ~65 lines by dropping what an agent already knows (category glosses, markdown snippets for trivial edits, the Step 5 checklist). Also fix Step 1: `git log <tag>..HEAD` lists already-released commits because tags live on release/X.Y branches; document the `git merge-base --is-ancestor` check instead. Closes lasp#281 Co-Authored-By: Claude Opus 5 <[email protected]>
The `git log <tag>..HEAD` range and the `git merge-base --is-ancestor <sha> <tag>` check are complements by construction, so the check could never report "already released" for a commit taken from the range it was meant to filter. It also ran in a separate shell, where `$LATEST_TAG` was unset, and failed open on the resulting error. The topology it rested on is false for the four most recent tags, which are ancestors of `main`. Replace both with one `git log --oneline --cherry-mark --left-right "$LATEST_TAG"...HEAD`, which marks cherry-picked duplicates `=` and release-branch-only commits `<` while keeping merge commits, and filter prereleases out of `LATEST_TAG` because `--sort=-version:refname` ranks 6.0.0rc4 above 6.0.0. Also state that the skill runs on an up-to-date `main`, name `AskUserQuestion` at the Scenario A/B decision, define `NEW_VERSION`, give the replace/insert verbs for the footer links so a second `[unreleased]` definition cannot shadow the first, note that `meta.yaml` nests `version:` under `package:`, and drop "or while preparing a release" from the description so it does not collide with `cut-a-release`. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
8455216 to
997e82c
Compare
|
@burakeyler — I've taken this over rather than sending seven suggestions back to you. All of them are applied in To be clear about what was wrong: the Step 1 mechanism came from #281 and from Your open acceptance item is closed. With this file in place, Claude Code lists the skill as 🤖 AI-assisted comment, reviewed and approved by @medley56 before posting. |
- Make adding a single entry to [Unreleased] the default path, with the history scan and the versioned-section conversion as conditional branches off it - Scope the "run on an up-to-date main" guard to the history scan. It previously applied to the whole skill, so an agent on a feature branch or a release/X.Y branch was told to stop rather than add an entry, blocking both documented workflows - Broaden the description to cover all three cases while keeping it clear of the cut/prepare/publish triggers cut-a-release owns - Cut the git log marker exposition to the two repo-specific facts: skip commits marked =, keep merge commits for their PR numbers Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- Lead with writing a single entry, the normal case right after implementing a change; it works on any branch - Frame the history scan as finding missed entries, covering both the release-time check and the rare catch-up, and note that finding nothing before a release is the expected result - Keep the version bump and section conversion last, reached only once a release version is in the metadata files Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #292 +/- ##
=======================================
Coverage 94.62% 94.62%
=======================================
Files 49 49
Lines 4203 4203
=======================================
Hits 3977 3977
Misses 226 226 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
2 participants
Closes #281
What
.claude/skills/update-changelog/SKILL.mdnow starts withname: update-changelogand adescriptionthat states both what it does and when to use it (update / fill in / catch up the changelog, or while preparing a release), so Claude Code can discover it.git log <LATEST_TAG>..HEADincludes already-shipped commits because tags live onrelease/X.Y, and usesgit merge-base --is-ancestor <sha> <tag>as the check, matching the wording in thecut-a-releaseskill from Add a cut-a-release skill #278. Also notes that[Unreleased]may be incomplete.The process itself is unchanged — this is a length/discoverability edit, not a redesign.
Other skills
update-changelogis the only skill onmaintoday;cut-a-release(#278) already has frontmatter.Verification
nameanddescription.🤖 Generated with Claude Code