6 ms·

Keep a Changelog

197 points by snake_case 12y ago

JohnTHaller 12y ago
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.
carbocation 12y ago
> 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 12y ago
  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.
eCa 12y ago
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/Changes/Spec.pod https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/... [2] https://metacpan.org/pod/Dist::Zilla https://metacpan.org/pod/Dist::Zilla [3] https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHasContent https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHa... [4] https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Changes https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Ch...
akerl_ 12y ago
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-convention 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.
jsankey 12y ago
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.
tomphoolery 12y ago
"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 12y ago
  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_ 12y ago
    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?"
JoshTriplett 12y ago
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.
- peteretep 12y ago
  I note that almost every CPAN module is on GitHub, and also almost every one has an up-to-date CHANGES file.
- Xixi 12y ago
  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.
- geofft 12y ago
  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 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.)
viraptor 12y ago
> 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.
- deleted 12y ago
  [deleted]
Xixi 12y ago
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.
philips 12y ago
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 12y ago
  > `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.
bsimpson 12y ago
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
Benjamin_Dobell 12y ago
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-dpkgchangelog 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/ http://xkcd.com/927/
teddyh 12y ago
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-Logs.html 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 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/distpractice.html#filenames http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/dis...
- Moru 12y ago
  not invented here-syndrome
- crististm 12y ago
  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?
  - teddyh 12y ago
    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).
hamstergene 12y ago
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 12y ago
  Indeed, your format looks exactly like what Perl's CHANGES spec stipulate: https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/Changes/Spec.pod https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...
olivierlacan 12y ago
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/30399830ce04b48049f881062984742990d5c260#diff-04c6e90faac2675aa89e2176d2eec7d8L74 https://github.com/olivierlacan/keep-a-changelog/commit/3039... Thank you :-)
- teddyh 12y ago
  > […] 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.
qznc 12y ago
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.
theRhino 12y ago
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'

197 points by snake_case 12y ago

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.

carbocation 12y ago

> 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 12y ago
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.

eCa 12y ago

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/Changes/Spec.pod https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/... [2] https://metacpan.org/pod/Dist::Zilla https://metacpan.org/pod/Dist::Zilla [3] https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHasContent https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHa... [4] https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Changes https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Ch...

akerl_ 12y ago

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

jsankey 12y ago

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.

tomphoolery 12y ago

"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 12y ago
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_ 12y ago
  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?"

JoshTriplett 12y ago

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.

peteretep 12y ago
I note that almost every CPAN module is on GitHub, and also almost every one has an up-to-date CHANGES file.
Xixi 12y ago
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.
geofft 12y ago
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 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.)

viraptor 12y ago

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

deleted 12y ago
[deleted]

Xixi 12y ago

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.

philips 12y ago

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 12y ago
> `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.

bsimpson 12y ago

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

Benjamin_Dobell 12y ago

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-dpkgchangelog 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/ http://xkcd.com/927/

teddyh 12y ago

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

Moru 12y ago
not invented here-syndrome
crististm 12y ago
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?
- teddyh 12y ago
  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).

hamstergene 12y ago

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 12y ago
Indeed, your format looks exactly like what Perl's CHANGES spec stipulate: https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/Changes/Spec.pod https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...

olivierlacan 12y ago

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

teddyh 12y ago
> […] 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.

qznc 12y ago

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.

theRhino 12y ago

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'