CHANGELOG.md is causing PR friction

[ianscrivener]

Because many PRs need to update CHANGELOG.md - it is frequently changing and getting PR merge conflicts. (PITA)

How can we manage CHANGELOG.md in a more frictionless way?

[ianscrivener]

3 solutions suggested by Claude

1. Union merge driver - 5 minutes, stopgap

# edit .gitattributes
CHANGELOG.md merge=union

Git concatenates both sides instead of conflicting. Conflicts vanish, but you get duplicated section headers and arbitrary ordering — someone tidies it at release. Fine for a week, not a fix.

2. Changelog fragments the recommended approach answer
Each PR drops a new file in changelog.d/ — e.g. changelog.d/312.added.md — containing one line. Nobody edits CHANGELOG.md. At release, a tool collates the fragments in order, writes the section, deletes them. Zero conflicts by construction, because no two PRs ever write the same path.

For a Python project like mflux: towncrier (most common) or scriv — which, yes, is literally Ned Batchelder's tool and shares your name. Awkward. JS-land equivalent is changesets.

3. Generate it entirely - most disciplined
Adopt Conventional Commits (feat:, fix:) and let git-cliff or release-please build CHANGELOG.md from history at tag time. The file becomes a build artifact — regenerated, never hand-edited, so it can't conflict. Cost: you're now enforcing commit message format on drive-by contributors, which is real friction on a high-velocity OSS repo.

As a community opensource project we must consider that some in our dev community may not be full time profesisional elite developers.

@anthonywu can a CHANGELOG.md solution be added to just?

Suggestions?

[fxd0h]

Data point, since both of mine hit it this week. #603 and #604 both conflicted on CHANGELOG.md in the same spot, one line appended to the same section. @anthonywu resolved one of them for me and his next comment was "now I need another approval".

That's where the cost is. Resolving it means touching the branch, and touching a green approved PR drops the approval, so a one-line collision turns into another round through whoever's around.

Of your three, fragments are the only one where two PRs never write the same path.

[ianscrivener]

@fxd0h, Can we somehow automate CHANGELOG.md fragments in the just pipeline?

[anthonywu]

tbh the way I would do it is get rid of the changelog.md file and use GitHub Releases primitives: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

the git commit messages and PR title/body of PRs since the last release tag is sufficient context to auto-generate release messages when it is declared, we just need to write a skill/hook to operate gh release during a distribution to pypi:

 $ gh release
Manage releases

USAGE
  gh release <command> [flags]

GENERAL COMMANDS
  create:        Create a new release
  list:          List releases in a repository

TARGETED COMMANDS
  delete:        Delete a release
  delete-asset:  Delete an asset from a release
  download:      Download release assets
  edit:          Edit a release
  upload:        Upload assets to a release
  verify:        Verify the attestation for a release
  verify-asset:  Verify that a given asset originated from a release
  view:          View information about a release

FLAGS
  -R, --repo [HOST/]OWNER/REPO   Select another repository using the [HOST/]OWNER/REPO format

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual
  Learn about exit codes using `gh help exit-codes`
  Learn about accessibility experiences using `gh help accessibility`

[ianscrivener]

@fxd0h, @plz12345 ... pls add your thoughts on ChangeLog... um changes?!

[fxd0h]

More data since the freeze lifted: the same [Unreleased] block needed four conflict resolves across #649 and #650 in one week, and at one point Anthony and I were fixing the same conflict in parallel without knowing it. I'd kill the per-PR changelog edit entirely.

I also think the replacement already exists. Every PR here writes its real substance in the template's What section, which says far more than any title. Kubernetes formalizes this with a release-note block in the PR body and harvests those at release time. We could do the same, and have the release step read the merged PRs since the last tag and draft the changelog section from those blocks, for whoever cuts the release to review before tagging. Nobody touches a shared file per PR anymore. --generate-notes can still add the PR links on the release itself, and whether the drafted section also lands in CHANGELOG.md is a detail to settle at the first release that uses it.

[fxd0h]

@ianscrivener I think you hit the wrong plz

@plz12345

[ianscrivener]

Good points Mariano...
Who are change logs for?
Are they for MFlux developers (DX) or MFlux users (UX) ?

Personally, I think there is a need for both! Perhaps

• CHANGELOG.md - UX audience. More product feature focussed
• CHANGELOG-DEV.md - DX audience - for (hard core) devleopers - use the "What" from the PR as you say

[plz12345]

I'm with Anthony. Get rid of the repo Markdown file and use Releases.