Hacker News Reader

In our case, we're writing "@changelog [quick summary of the change]" somewhere in our commit message when we think that the commit actually warrants a change log entry.

Then as part of the release process, somebody (usually me) uses `git log --grep` to find all the commit messages that developers thought to be change log relevant and writes a document that can be consumed by end users (including screenshots of the features etc).

This way end-users can still be informed about changes (most don't care, some notice and complain even when one pixel has moved to a different spot), but we never have issues with merges or rebases (at least not related to change log maintenance :p)

Also, in my opinion, keeping a change log for developers is completely unnecessary these days with git and other tools to provide very quick and easy access to the revision history.

But for end-users it still makes sense, though it of course has to be on a higher level than individual commits.

I agree with the argument that a NEWS file is the right thing here and already pretty close in spirit to what's being advocated. Among other things, "CHANGELOG" as a name evokes GNU-style ChangeLog files, which is the total opposite of what this site is advocating: https://sourceware.org/git/?p=glibc.git;a=blob;f=ChangeLog

But regarding git conflicts, I've set up dpkg-mergechangelogs as a global merge driver and it works decently well for cherry-picking things within Debian packages represented as git repos. In ~/.gitconfig:

    [core]
        attributesfile = ~/.gitattributes
    [merge "dpkg-mergechangelogs"]
        name = debian/changelog merge driver
        driver = dpkg-mergechangelogs -m %O %A %B %A

and in .gitattributes:

    debian/changelog merge=dpkg-mergechangelogs

So the author of this spec could write a similar command and advocate for similar configuration. (The bottom of the dpkg-mergechangelogs manpage mentions this, but doesn't mention how to make it global for all repositories.)

I quite agree with this: the end goal of a CHANGELOG.md (or NEWS.md if you prefer) should be to give the end-user a summarized view of the changes since the last release, organized logically by order of importance, not chronologically by order of commit.

Something like: security issues, breaking changes, major features, major bugfixes, minor features, minor bugfixes.

The last project I was working on only edited the changelog file when a release was cut. As we tagged each release with a version number, it was easy to get the commit messages since the last release with:

    lastTag = `git describe --abbrev=0 --tags`
    git log --oneline --no-merges #{lastTag}..HEAD | cut -c 9- | sort

Then you just need to edit that list down to the relevant details. This was part of a release script which also added things like increasing the version number, generating md5 hashes for the binaries, date etc.

If you have something like a changelog, it's important to keep the audience in mind. In this case the audience was mainly the internal test department and marketing. Testers also had access to the bug tracker of course and only used the changelog to get an overview. Marketing and support used the changelog as the basis for their communication with customers.

I note that almost every CPAN module is on GitHub, and also almost every one has an up-to-date CHANGES file.

> Projects that still insist on maintaining a changelog file in git end up constantly fighting git's conflict resolution, and they make rebase almost completely unusable.

It's actually pretty simple - you keep CHANGELOG updates to their own commit, and just aggressively rebase into that commit as you prepare the release. The release owner is the only person who works on the CHANGELOG. We do that at Snowplow and it works really well. Here is the WIP commit for the CHANGELOG for the next Snowplow release: https://github.com/snowplow/snowplow/commit/a862b1e4ab935184...

When we finish a release, the CHANGELOG becomes the GitHub release notes: https://github.com/snowplow/snowplow/releases/tag/r60-bee-hu...

We are approaching 1 issue : 1 commit : 1 CHANGELOG entry but it's not always possible, and a huge number of open source software users are not technical enough to parse a git log anyway.

I think neither a CHANGELOG or a NEWS file has a place in a git repo.

Every file in every commit should be meaningful for the given commit. These are obviously usually source files or even documentation of the current behavior of the software. The problem with CHANGELOG and NEWS files that they are not meaningful to every single commit only for commits that are tagged as releases.

I don't know what would be a good practice to manage change logs in a repo. I'm sure that it shouldn't be in a project's git repo though. Maybe having a separate git repo for managing releases would help, like have your original project as a submodule and keep release specific files in this separate repo. Obviously it looks more complicated but it's better than managing merge conflicts between CHANGELOG files when there is no meaning of the CHANGELOG for the merge commit anyway.

The ChangeLog file can certainly be cut, but the NEWS file? The NEWS file is only changed when a new release is made. Otherwise, the file is unchanged. I see no reason it should not be in the repository.

Gitlab guys found a working method to fight the git conflict on the CHANGELOG file: https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-con...

Sumup:

> At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog. People can insert their entry at a random location in the changelog. There is still a chance of conflict when two merge requests change the same line but it is greatly reduced. It looks a bit strange to have these empty lines on top so we added a comment to explain their purpose..

Seems they no longer use this method. Instead they use `CHANGELOG merge=union` in a .gitattributes file at the root of the repository. That means that conflicting merges take changes from both sides of the conflict. It's what you usually want with a changelog.