Change way Changelog is handled in pull-requests

[nh2]

The way ChangeLog.md is handled currently is really subobtimal.

Every time somebody pushes a new feature, everybody else has to rebase all their pull requests because now obviously ChangeLog.md conflicts:

This branch has conflicts that must be resolved
Only those with write access to this repository can merge pull requests.
Conflicting files
Cabal/ChangeLog.md

[nh2]

Other projects handle that in better ways, for example by generating the changelog at release time from the commit messages, or from a file added per commit or PR.

Maybe Cabal could use such a method as well?

[phadej]

@nh2 I sympathise this. With servant I do assemble Changelog semi-manually before releases.

If we'd use commit messages, we'd need to be raise the quality bar of commit message quite high (for everyone!)

I like both the from PR (Adding a to-be-filled Changelog entry section to PR template),
as well as adding a file. There is a trade-off between release manager's time and contributors convenience, so @23Skidoo have the final word on this.

[23Skidoo]

Having a PR template section makes sense, then whoever merges the PR will be responsible for adding the changelog entry in a separate commit. I'm -1 on going back to generating the changelog at release time.

[nh2]

Making the merger do extra work on merge sounds unecessary to me.

Why don't we just use an approach where the person merging the PR doesn't have to do lots of manual work, but that can be fully scripted?

Here are some approaches that other projects use:

Approach 1: A changelog directory

A next-changelog directory, where there's one file per changelog entry. Contributors must drop a file here as part of their commit or PR. At release time, the contents of all files is simply cated and copy-pasted into ChangeLog.md, and the directory emptied.

Approach 2: Changelogs in commits

Each commit message that's changelog-worthy includes a section:

Changelog:
* Bla bla bla ...

that can be grepped out easily (up to the next blank line).

[nh2]

The current approach is certainly not maintainable:

We have 66 open PRs right now, and if each of them properly adhered to adding to the bottom of the changelog, we'd have to rebase + conflict-resolve all 66 PRs after the next merge.

[23Skidoo]

Making the merger do extra work on merge sounds unecessary to me.

Not that big of a deal IMO, I usually/often want to do small edits to the changelog notes anyway.

[23Skidoo]

Also, is there a way to customise Git's auto-merging per file? It should be easy to resolve these types of conflicts automatically once you have a little extra info about the semantics of the file.

[23Skidoo]

Apparently you can set merge=union in .gitattributes, maybe that'll work for us?

http://krlmlr.github.io/using-gitattributes-to-avoid-merge-conflicts/

[23Skidoo]

...but it looks like GitHub doesn't support merge=union: isaacs/github#487

[23Skidoo]

I've added merge=union to both changelog's Git attributes anyway, at least the manual merging will be easier.