How to avoid merge conflicts with release note updates?

[drewj-tp]

A semi regular occurrence, at least for me in the few PRs I've worked on recently, is to have merge conflicts in the release notes file. This is somewhat unavoidable if two PRs add a new line at the bottom of the release notes file. This means a PR that is approved and ready to go, needs one more iteration before it can go out the door.

How can we both keep the functionality of the release notes while reducing these merge conflicts?

Personal recommendation

I've used towncrier in the past, and groups like pytestand pip do as well. Developers write a single "fragment" file e.g., news/1234.fix.rst. Upon invocation, towncrier collects all the news files and generates the changelog from them. Breaking down that file name

• news/ is a configurable directory where the fragments are stored.
• 1234 is the ID of the ticket or PR or some other identifier data that originated this entry
• fix is the fragment type. A variety of defaults are included, and more can be added in configuration

Prior to release, someone would need to run the towncrier command to build the release notes. This will automatically git rm the fragment files (unless told otherwise) since they aren't really needed after the release notes have been made.

Other ideas

Quick searching brought up these options

• https://github.com/gyptazy/changelog-fragments-creator
• https://github.com/github-changelog-generator/github-changelog-generator
• GitHub auto-generated release notes
  • Lives on the github release page, not so much in our docs

[john-science]

Honest question, what's the benefit of towncrier over just having a changelog in the release notes?

[opotowsky]

I think it's that devs are adding one file at a time (no merge conflict), whereas the changelog would have the same merge conflict issue as the release notes do.

[drewj-tp]

@opotowsky hit part of it: devs make one fragment (or more) for the thing their working on.

But the fragments != changelog.

Right before a release, someone runs towncrier and it removes the fragments and makes the changelog from those fragments. Add that to a PR and ship it

[john-science]

Hmm... So every release I go through and hand-edit the release logs because I want them to be a LOT more consistent and focused than the devs tend to throw into their PRs.

Is there room for that with towncrier?

[drewj-tp]

Absolutely. It still generates a file, e.g., CHANGELOG.md or doc\release\0.4.rst that can be edited before committing and pushing to the repo during release