
Keep a Changelog - snake_case
http://keepachangelog.com/
======
teddyh
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...](https://www.gnu.org/prep/standards/html_node/Style-of-Change-
Logs.html)

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](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...](http://en.tldp.org/HOWTO/Software-Release-
Practice-HOWTO/distpractice.html#filenames)

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

~~~
teddyh
> _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.

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

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

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

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

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

~~~
shared4you
Indeed, your format looks exactly like what Perl's CHANGES spec stipulate:
[https://metacpan.org/pod/distribution/CPAN-
Changes/lib/CPAN/...](https://metacpan.org/pod/distribution/CPAN-
Changes/lib/CPAN/Changes/Spec.pod)

------
eCa
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/...](https://metacpan.org/pod/distribution/CPAN-
Changes/lib/CPAN/Changes/Spec.pod)

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

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

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

------
Benjamin_Dobell
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...](https://www.debian.org/doc/debian-policy/ch-
source.html#s-dpkgchangelog)

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

[http://xkcd.com/927/](http://xkcd.com/927/)

------
viraptor

        > 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](https://www.debian.org/doc/debian-policy/ch-source.html)
describes debian changelog format which applies to all .deb packages for years
now.

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

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

~~~
Terr_
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?"

------
bsimpson
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](https://github.com/ryanflorence/rf-release)

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

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

------
qznc
The best and most extensive changelog I ever saw is D's:
[http://dlang.org/changelog.html](http://dlang.org/changelog.html)

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

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

~~~
girvo
_> `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.

------
akerl_
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...](https://github.com/tech-angels/vandamme/#changelogs-convention)

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

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

------
olivierlacan
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...](https://github.com/olivierlacan/keep-a-
changelog/commit/30399830ce04b48049f881062984742990d5c260#diff-04c6e90faac2675aa89e2176d2eec7d8L74)

Thank you :-)

~~~
teddyh
> […] _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.

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

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

------
theRhino
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'

