ci: solution to CHANGELOG.md merge conflicts (auto-generated Next Release)#259
Open
galjos wants to merge 1 commit into
Open
ci: solution to CHANGELOG.md merge conflicts (auto-generated Next Release)#259galjos wants to merge 1 commit into
galjos wants to merge 1 commit into
Conversation
Every PR currently has to edit CHANGELOG.md, so two open PRs always
conflict on the same lines as soon as one merges to dev. Drop the
per-PR requirement entirely and lean on the conventional-commit
prefixes already enforced by .githooks/commit-msg: at release time
git-cliff renders the Next Release section from commits since the
previous tag, grouped by section, deduplicated, prefix-stripped.
Seamless with the current state:
- scripts/update_changelog.py preserves any curated Next Release
content in CHANGELOG.md verbatim and just stamps it with the
version. So the v0.7.0 release (next one) ships the already-
curated bullets unchanged - nothing is skipped, deleted, or
hand-selected.
- For subsequent releases the section will be empty when the script
runs, so git-cliff fills it in automatically from commit subjects.
Maintainer can still hand-edit the generated section in the release
PR before tagging.
- Legacy changes/<slug>.<type>.md fragments (left over from the
previous attempt) are still folded into the matching section, so
nothing in flight gets lost either.
Verbosity is controlled in cliff.toml:
- merge / revert / [skip changelog] commits are dropped,
- style / format / chore / admin / example types are dropped,
- commits are grouped under PQ's existing section headings so a
20-commit release renders as ~6 short sections, not one wall,
- identical subjects are deduplicated within a section,
- each bullet is the commit subject only, no body.
The Check Changelog CI gate is removed. The PR template is unchanged;
contributors just write a good commit subject and the changelog
generates itself.
Smoke-tested both paths on the actual CHANGELOG.md:
- curated path: existing ## Next Release content kept intact and
reordered into canonical section order; legacy fragment folded in;
section stamped as v0.7.0.
- empty path: ## Next Release emptied, git-cliff produced 7 sections
(Enhancements, Bug Fixes, Build, CI, Tests, ...) from the commits
since v0.6.4, all bullets terse and grouped.
ape33
approved these changes
Jun 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@97gamjak — draft proposal to stop every PR conflicting on `CHANGELOG.md`.
Every PR currently has to edit the same `## Next Release` lines, so two open PRs always conflict on it. The fragments approach from #235 reduced the surface but contributors never adopted it (every PR since edits `CHANGELOG.md` directly). Cleaner fix: drop the per-PR requirement and let the conventional-commit prefixes the commit-msg hook already enforces drive an auto-generated section at release time via `git-cliff`.
How it works
Keeping the section terse with many commits
`cliff.toml` drops merge / revert / `[skip changelog]` / style / chore / admin / example commits, groups the rest by section (~6 short sections instead of one wall), and deduplicates identical subjects. Each bullet is the commit subject only. The release PR still goes through review — you can hand-edit the generated section before tagging.
Seamless with current state
The script preserves the existing curated `## Next Release` bullets verbatim. v0.7.0 ships the curated content unchanged; auto-generation only kicks in for subsequent releases. Nothing skipped, deleted, or hand-selected.
Smoke-tested both paths on the actual CHANGELOG.md: curated → reordered into canonical section order and stamped; empty → git-cliff produced 7 grouped sections from commits since v0.6.4, terse and deduplicated.