Keep a Changelog | Hacker News Reader

Keep a Changelog

keepachangelog.com

197 pointssnake_case43 comments

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.

For an actual log of individual changes, that's what "git log" is for; any project that pre-dates git should "git mv ChangeLog ChangeLog.pre-git". And if your "git log" output isn't highly readable, write better commit messages and group changes into more logical commits; once you stop breaking "git rebase -i", that gets a lot easier.

Some of this advice potentially makes sense, but for a NEWS file, not a changelog. A NEWS file has one top-level heading per release, containing the release notes for that release, summarizing the key user-visible changes. However, that file should not attempt to track every change, should not contain times or dates, and should get grouped in logical chunks rather than chronological order.

And while it can potentially make sense to update that file as part of the commit introducing a new user-visible change, that also reintroduces the same conflict and collaboration issues as a changelog, so personally I only update NEWS files right before a release. I run a script that generates a properly formatted NEWS entry based on the version and git commit messages (turning each one into a markdown bullet-list entry with indentation), then edit the result to add headings, group entries under those headings, and delete any non-user-visible changes that don't merit a release note.

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

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.

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.)

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 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.

> 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.

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.

The author seems not overly familiar with the history and conventions of releasing software.

> Is there a standard change log format?

> Sadly, no. But I want to change that.

There is a standard change log format: https://www.gnu.org/prep/standards/html_node/Style-of-Change...

Most GNU tools (and many others) use this format.

The Debian changelog format which most people have seen is based on that format, and is compatible with it.

> What’s the point of a change log?

> To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Oooh, they mean a NEWS file. Standardized like so: https://www.gnu.org/prep/standards/html_node/NEWS-File.html

> What should the change log file be named?

> Well, if you can’t tell from the example above, CHANGELOG.md is the best convention so far.

> Some projects also use HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

> It’s a mess. All these names only makes it harder for people to find it.

Please use standard names. Details here: http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/dis...

not invented here-syndrome

I have considered lately the equivalent of the "engineer's notebook" but I am not aware of such files in most notable software projects. It is supposed to record and communicate project challenges, dead-ends, attempts etc. to other contributors (probably like HISTORY?)

Does it make any sense to do that in a project?

The file most likely to contain such information would probably be the HACKING file, which I’ve seen many projects use to contain an introduction for developers of the software itself (as opposed to building instructions or the user’s manual).

I am. Based on the current status of change logs in many open source projects ((absence, poor quality, irregular updates), I believe these conventions can be improved upon and clarified. At the very least they can be explained better than a two line text file with not a single example.

The GNU conventions for change logs and news files are not exactly self-explanatory (semantics matter), which probably explains how rarely they have been followed to the letter. I have no data to back this up, but I doubt people who use and depend on open source software would discard this claim.

Now it's interesting to see this initiative mocked as a "not invented here syndrome" (Moru's comment). I did not define these guidelines, I merely gathered them from existing open source projects which were exceptionally good at communicating changes. The poor examples and the frustration that fueled this project came from projects that did the opposite:

- inconsistent (file naming, change categories, etc.)

- dumping git diffs which provides absolutely no value to end-users (OSS software users who need to regularly update their dependencies)

- littered with references to irrelevant issue trackers (which did not provide clarifications regarding the changes)

- poorly written with the wrong audience in mind (fellow project collaborators who have context vs. external users who don't)

- not given any dates or given confusing regionally-flavored dates

- and the crux of my frustration: not singling out and emphasizing API breaking changes and deprecations

Anyway, please don't dismiss this project because a convention exist in one community. This convention is not being followed for now and I would really appreciate your help in improving the status quo: https://github.com/olivierlacan/keep-a-changelog/issues

Thanks.

Your project to make more projects adhere to standardized naming conventions and follow more rigorous documentation and release practices is laudable, and I support it wholeheartedly.

Your project to create a standard format and file name for what you want is unnecessary, since these exist already. Furthermore, you seem aware of this, and seem to want to change the existing standards to your history-naïve preference. You don’t even go to the projects which are the keepers of said standards, but instead set yourself up as a competing standards body. This does not endear you to people such as myself, who are on the whole happy with the current system, and see no benefits to your proposed changes.

Relevant XKCD: http://xkcd.com/927/

The GNU standard is good and all, but I've found that it's horribly out of date.

- The name "NEWS" is not what users expect. I used to have a NEWS file which documents major changes in a high-level way, per the GNU standards. But I kept getting requests from users to "keep a changelog", and I kept getting questions from users about where the changelog is. Apparently most users never bother to check the NEWS file; they don't even associate the filename "NEWS" with what they're looking for. 95% of the users associate that concept with the word "changelog". "Changelog" is the new "NEWS". After several years, I gave up the resistance and renamed by "NEWS" to "Changelog".

- The actual Changelog format, per the GNU standards, is useless in my opinion now that version control systems have gotten so good. In my opinion, the git history is exactly what the GNU changelog tried to be, with the added benefit that the git history is much easier to browse, query and manipulate.

> The name "NEWS" is not what users expect.

This, I suspect, depends on your user base. Apparently your users expect the name "changelog". (Do they all use that exact term? Could this usage be traced to a single source, common among your users?)

> The actual Changelog format, per the GNU standards, is useless in my opinion now that version control systems have gotten so good.

Indeed, I believe even GNU Emacs has abandoned (or is about to abandon) it, now that they have switched to git.

Yes my users all use the term "changelog". And outside of traditional GNU projects, I've never seen anybody talk about "the NEWS file". All I've seen is people mentioning "the changelog", by which they mean that which the GNU NEWS file is meant for.

You can write the commit messages in ChangeLog format. The format is independent of how you store it! You can then create ChangeLog files from the history for source tarballs. In fact many GNU projects seem to do that now.

Other projects (GNU Emacs) still continue to use ChangeLog files because it is easier to correct ChangeLog entries than editing the commit history (which in git is destructive).

Why use so many levels of markdown headers? That prevents pasting parts of changelog as a section of another document (e.g. release notes), creates cacophony of fonts when converted to html, and is overall unnecessary because it adds no meaning nor reading convenience. It looks like this guy is overcomplicating quite a simple thing.

I've been maintaining changelogs for pretty much all my career, in simpler format:

    - at the top of file go unreleased changes, without a header

    1.6.1: 2005-01-22
    - fixed: one
    - fixed: another

    1.6: 2004-11-18
    - fixed: this
    - added: that
    - redesigned preferences dialog

There is zero markup noise here, and when interpreted as markdown it looks just as nice.

Indeed, your format looks exactly like what Perl's CHANGES spec stipulate: https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...

From the article:

Is there a standard change log format?

Sadly, no. But I want to change that.

... wait, what?

There are plenty of standardised change log formats. Take for example Debian's changelog format:

https://www.debian.org/doc/debian-policy/ch-source.html#s-dp...

Or are they talking about one standard to rule them all? In which case...

http://xkcd.com/927/

    > Is there a standard change log format?
    Sadly, no. But I want to change that.

What's missing from some formats which already exist and are pretty popular? https://www.debian.org/doc/debian-policy/ch-source.html describes debian changelog format which applies to all .deb packages for years now.

In Perl a standard had evolved[1] that is a bit less structured, but designed to be machine read/writable while still being human centered.

And if you build your distributions with Dist::Zilla[2] you can use plugins to ensure that you have an entry for your release[3] and that the changelog follows the standard[4].

[1] https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...

[2] https://metacpan.org/pod/Dist::Zilla

[3] https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHa...

[4] https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Ch...

"Because log diffs are full of noise. Can we really expect every single commit in an open source project to be meaningful and self-explanatory? That seems like a pipe dream."

I thought this was the point of squashing your commits together when making a pull request, so the `git log` of master reads like a changelog. You can also interactively rebase and change commit messages if the wording is confusing.

The definition of "meaningful" might be a bit soft here. When figuring out what changed in a release, I don't really care that you "converted tabs to spaces" or "refactored method name based on intent" or any such structural change. The git log is generally too noisy to be used for describing a release.

Exactly: There are two very different use-cases and audiences.

Your version-control system should be helping programmers understand the evolution of the codebase, or the reasons behind certain line-changes... especially when those changes were made by someone else long ago.

The changelog, on the other hand, is for a less-technical (or at least less-involved) audience. It has to summarize the net-change which occurs in a way which is meaningful to people asking different sets of questions. Such as: "What are the new features?" and "Did they change anything about X?"

I just started using rf-release[1] to manage both maintaining a changelog and releasing to npm.

It maintains a CHANGELOG.md file that includes all the changes that have happened between version numbers. It chooses which commits to include by filtering on [added], [changed], [deleted], or [fixed]. Thus, if you'd like a change to appear in your changelog, just include one of those tags in the relevant commit message.

Seems like a nice way to prevent maintaining an npm package from becoming a chore.

[1] https://github.com/ryanflorence/rf-release

> Dumping a diff of commit logs. Just don’t do that, you’re helping nobody.

Depending on how you write your comments for commits, merges, or tags, it seems that you could dump those logs and have quite a reasonable changelog.

I think a good approach to this when using git, that I've tried to keep in my own projects of late, is to keep your master branch only merge commits and curate the merge commit messages explicitly to be human readable descriptions of the changes. I think it's entirely possible to generate good changelogs out of this and proper tagging, but there probably need to be a few less awkward tools for maintaining it than just directly using git commands.

Before you run to educate me about GNU's change log style guide, please go read this: https://github.com/olivierlacan/keep-a-changelog/commit/3039...

Thank you :-)

> […] or the two-paragram GNU NEWS file "guideline". The GNU style guide is a nice start but it is incredibly naive. There's nothing wrong with being naive but when people need guidance, it's rarely very helpful. Especially when there are many situations and edge cases to deal with.

Your project could easily transition to become a project to document, codify, and standardize existing NEWS file practices and conventions and also submit these as a patch to the GNU coding standards. This would be an effort I could support.

The best and most extensive changelog I ever saw is D's: http://dlang.org/changelog.html

It documents and explains (with examples!) everything normal D programmer needs to know.

I like projects that put their changelogs into git tags with `git tag -s`. On GitHub these even get shown by default on the releases page. A nice side effect is that you sign the hash of the release too.

> `git tag -s`

Know of somewhere that explains how to do that well? I'm a big fan of keeping all of my workflows related to project in git as much as possible, especially if GitHub picks it up correctly.

It's worth noting that they link to Vandamme, the library used by Gemnasium for parsing changelogs, but Vandamme recommends a slightly different format for the file:

https://github.com/tech-angels/vandamme/#changelogs-conventi...

I prefer Vandamme's recommended format, but I'd greatly appreciate this site's format as well.

I follow this set though I hadn't read about it before. I do one additional tag that is not mentioned. "Updated", which is used for translations. So, each release has a line similar to this:

Updated: French, Portuguese Brazilian, Spanish International

It doesn't affect the app other than those specific translations and it makes it easy to pinpoint when a given translation was last updated.

Good issue tracking tools can produce changelogs for you, which is preferable to maintaining a redundant, separate log manually. It also encourages good practices like tracking all user-visible changes and keeping issue summaries accurate and readable.

Nicely formatted changelogs are amazing for third-party tools: at requires.io we try to gather as many changelogs as possible, but oftentimes there are simply none available.

note 'unreleased' is not the right word to use for the section above the last version. this is because a version is not necessarily a release. it should be called 'latest'

Reply on news.ycombinator.com