13 ms·

Keep a Changelog

137 points by vdfs 10y ago

mcescalante 10y ago
This has cropped up once or twice before. Previous discussion from February 2015: https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627
- olivierlacan 10y ago
  Sure thing, but it's evolved quite a bit since then. We've introduced a versioning system a few weeks ago, and we now have 8 translations other than English thanks to contributors, so I'd wager it's newsworthy. :-) I've covered these recent changes in a post that didn't quite make it to the front page recently: http://olivierlacan.com/posts/logging-changes-all-over-the-world/ http://olivierlacan.com/posts/logging-changes-all-over-the-w...
  - mcescalante 10y ago
    True! I mainly posted the previous discussion because I like to go back and look at the comments and see how it's evolved. Thanks for sharing the post :)
necessity 10y ago
Org-mode is specially useful for this task. It is plain-text, has built-in support for sections, dates, arbitrary tags, and can even export to Markdown (or HTML, or Latex) if you really want that. Besides other wonderful features such as Babel.
- olivierlacan 10y ago
  People have mentioned Org-mode repeatedly throughout the years since I first wrote down the thoughts that became keepachangelog.com but I'll be honest, Org-mode doesn't seem to be broadly used in the greater open source community whereas Markdown (or just plain text) CHANGELOG.md, NEWS.md, History.md, and others are far more common. There's surely personal bias at play, but I'm far more concerned with people keeping a changelog in the first place to worry too much about how exactly they do it. If Org-mode is what they go with, fine, but what we're facing right now is hordes of open source projects that people end up taking on as direct or transitive dependencies and which do not document their evolution in any meaningful way.
mianos 10y ago
Someone should send this to the guys who maintain the google internal apps like gmail and google now.
- TeMPOraL 10y ago
  Or Skype, which just tells you something like "we've updated your Skype application, which among other things means less bugs and improved performance".
exratione 10y ago
I'd argue that the goal of creating a good, useful changelog can be one of the forcing motivations to establish a working process for commit documentation and great, informative, useful commit messages. If that means git log gardening after the fact, then so be it, but good documentation (of history here) is always worth the work. The activities of programmer-archaeology are always made so much easier if you have a screed of history for each area of interest in the codebase. Sadly that's still rare, even in groups that do the necessary work to maintain their documentation for the current state of HEAD. There are many times when history matters, is relevant, and those who do not learn it are doomed to repeat it - or at the very least build elaborate theories to explain what happened in the past in order to understand how the present came to be where it is. The great changelog built on great commit history is probably hard to do outside of a small, focused group. On the other hand, the pull request process has emerged and developers have embraced that level of work, so it feels like it should be achievable.
- olivierlacan 10y ago
  I agree. Maintaining a changelog can be certainly be more difficult in large projects (although I don't think it has to be). I do think changelogs are a manifestation of the maintainers' care with regard to end-users. It signifies that they don't simply focus on the quality of the project itself but also how the project's evolution is perceived and understood by end-users and fellow contributors. It's strange to me that anyone would consider especially open source software as something so good and obviously beneficial that the archeology you mention would be a fact of life for end-users. It betrays a misconception about the value of software in a vacuum: without tests, code documentation, interface design, and change documentation (a changelog). The best algorithm is useless without proper tests verifying how it functions against real input; it's obscure without good documentation highlighting its quirks and design decisions, and if it evolves without clear explanations within a changelog then the changes in its behavior will remain mysteries to end-users as long as they don't go deep inside the code to understand how it worked before and how it works now. I've had to do this kind of programmer-archeology on numerous production dependencies (transitive or otherwise) in the past and the resulting frustration is very much the fuel that motivated me to make keepachangelog.com
skybrian 10y ago
This is fine for smaller, low-velocity projects, but tends to result in merge conflicts in high-velocity projects. An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.
- derefr 10y ago
  I don't see how; presumably a CHANGELOG should only be updated as part of release engineering, not during development. It's a document owned by whoever bumps the version number.
  - bluejekyll 10y ago
    I find it easier to maintain one while you make the changes, thus I would see the issue being referred to.
  - chrismorgan 10y ago
    Speaking in the context of an open-source project: Writing a changelog progressively is the only way you’re likely to end up with it being good. Consider the whole point of the “unreleased” section, too. If you put it off, you’ll just keep on putting it off, and when you finally do make a release you’re unlikely to put enough effort into the changelog. Your changelog will be better if you write it at the time of development, not release. To be sure, you’ll want to check over it at release time or even before then, but there’s no rule against amending the changelog at any time.
- olivierlacan 10y ago
  A common convention we showcase in the Keep a Changelog changelog itself (https://github.com/olivierlacan/keep-a-changelog/blob/604e382bf3a438613691405efb072769fde22e08/CHANGELOG.md#unreleased https://github.com/olivierlacan/keep-a-changelog/blob/604e38...) is to have an [Unreleased] section at the top of the changelog. It rarely conflicts with other branches of a project because it only becomes a version prior to or after a merge into the main branch (trunk/master/etc.). I'd agree this is an area we need to clarify for version 0.4.0 and forward.
kitsuneudon 10y ago
The changelog on a lot of popular apps on the Play Store has just become a place to promote stuff, not show off whats new.
bertr4nd 10y ago
I hope this is different from what this article is advocating, but I worked on a project that kept per-sub directory changelogs that were intended to track every commit to every file in a directory. Our tech lead basically had to nag everyone to write them, and it felt like a big waste of time (Note, this was not an open source project, and the article specifically speaks to OSS.)
- olivierlacan 10y ago
  Yeah, this is definitely not what I'm advocating. That sounds insane to me. Several contributors have pointed out that these conventions can be useful beyond the realm of open source so I think we've tried to make it a bit more general. It is definitely based on open source conventions though. An open source project like Rails has different components all developed within a single repository although they're packaged up independently for release. Each different component has a root level changelog that documents its changes and there isn't a centralized changelog for all of Rails. In some ways it's problematic because you can't see a merged changelog for all core components of Rails but it's also useful when you're only worried about changes to the ORM component since you'll only see changes pertaining to it within its own changelog. In my mind a changelog is a root-level concern for a single piece of software, regardless of how many isolated components it's composed of. Basic tooling should be able to centralize each changelog (as long as versions are synchronized, but that's another issue) and ideally you should be able to filter by sub-component. This is definitely not something we've created any guidelines for yet. So if you have any thoughts on the matter, feel free to suggest them: https://github.com/olivierlacan/keep-a-changelog/issues https://github.com/olivierlacan/keep-a-changelog/issues
kazinator 10y ago
Do not keep a ChangeLog; it is redundant w.r.t. your git commit messages and causes useless merge conflicts when you cherry pick, rebase, etc. Do use ChangeLog format for commit messages!
- spb 10y ago
  It sounds like you're confusing what the author is describing with GNU "Change Logs" (https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs https://www.gnu.org/prep/standards/html_node/Change-Logs.htm...), which track every source file change and are indeed redundant with `git log` (or any other version control system record). This is calling for more use of what GNU calls a "NEWS file" (https://www.gnu.org/prep/standards/html_node/NEWS-File.html https://www.gnu.org/prep/standards/html_node/NEWS-File.html), which is what virtually everybody else means when they say "changelog". Per the page itself: > Why can’t people just use a git log diff? > Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states. > As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.
  - ChuckMcM 10y ago
    I tend to agree with both of these comments, that git commits are a very acceptable (and actionable change log) and that git log diffs are full of noise. That doesn't invalidate them as change logs though. I've got a command that will add everything that has changed in a directory tree except for ignored files, into a commit. And it is very helpful to write in the commit exactly what you're doing . You do this once a day and you've got an excellent log not only of how you have changed things but you can hop back to a previous commit and reset to a previous day. Now when it comes time to create a pull request ... Then you can go back and rebase and squash from the original start, and things into a commit history that is explainable and readable for the project. The only thing that would make this even more seamless if you could do a split-squash where you take a commit, "ungroup" it into its individual changes, then put the changes into their respective commits, and then squash those with the commits for what something should be at the end point.
edoceo 10y ago
This is right inline with a 'relnote' project I was working on. Mapping git logs to customer facing messages. Multiple commits/merges with terse engineer speak rewritten by English majors to concise sentences.
Twisell 10y ago
This project "visual changelog" usually blow my mind at every release. https://www.qgis.org/en/site/forusers/visualchangelog216/index.html https://www.qgis.org/en/site/forusers/visualchangelog216/ind... And this is exactly the opposite of a git commit only changelog. They put great effort in it so that everybody wait for it eagerly, and it might one of the reasons they got lots of sponsors and users donations.
- dividuum 10y ago
  Same with the Unreal Engine Release Notes (https://docs.unrealengine.com/latest/INT/Support/Builds/index.html https://docs.unrealengine.com/latest/INT/Support/Builds/inde...). Every time it is linked somewhere I just have to look at all the new shiny features despite not having any interest in using it at the moment.
  - TeMPOraL 10y ago
    Holy hell! This is amazing! I just read both changelogs (QGIS and UE) and found them very interesting even though I'm not doing anything with either of them. I can imagine making such visual logs is much more time-consuming than just browsing through commit logs since last release and retyping commit messages in plain English, but the potential of such visual logs to actually get read and understood is much greater. My question is - is there any tool that one could use to quickly capture a few seconds of a selected region of the screen as a video/GIF? Preferably one that would subsequently allow to throw away some frames from the beginning and ending. Such a tool would speed up the process of creating visual changelogs quite a bit.
    - yeldarb 10y ago
      Yes, LICEcap is good for this: http://www.cockos.com/licecap/ http://www.cockos.com/licecap/
      - dividuum 10y ago
        On Linux there is recordmydesktop and its gui frontend gtk-recordmydesktop. I don't have a lot of experience using it, but a few tests worked as expected.
ashitlerferad 10y ago
The Debian advice for changelogs: https://www.debian.org/doc/manuals/developers-reference/ch06.en.html#bpp-debian-changelog https://www.debian.org/doc/manuals/developers-reference/ch06... https://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs https://www.debian.org/doc/debian-policy/ch-docs.html#s-chan...
orta 10y ago
Agreed, in the last few months I've been using Danger (http://danger.systems http://danger.systems) to ensure that the OSS projects I work on ( CocoaPods/CocoaPods, artsy/eigen, artsy/emission ) all have consistent Changelogs. Works out nicely.
dblock 10y ago
There's a beginning of an automation library for http://danger.systems http://danger.systems in this vein, https://github.com/dblock/danger-changelog https://github.com/dblock/danger-changelog.

137 points by vdfs 10y ago

This has cropped up once or twice before. Previous discussion from February 2015: https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627

olivierlacan 10y ago
Sure thing, but it's evolved quite a bit since then. We've introduced a versioning system a few weeks ago, and we now have 8 translations other than English thanks to contributors, so I'd wager it's newsworthy. :-) I've covered these recent changes in a post that didn't quite make it to the front page recently: http://olivierlacan.com/posts/logging-changes-all-over-the-world/ http://olivierlacan.com/posts/logging-changes-all-over-the-w...
- mcescalante 10y ago
  True! I mainly posted the previous discussion because I like to go back and look at the comments and see how it's evolved. Thanks for sharing the post :)

necessity 10y ago

Org-mode is specially useful for this task. It is plain-text, has built-in support for sections, dates, arbitrary tags, and can even export to Markdown (or HTML, or Latex) if you really want that. Besides other wonderful features such as Babel.

olivierlacan 10y ago
People have mentioned Org-mode repeatedly throughout the years since I first wrote down the thoughts that became keepachangelog.com but I'll be honest, Org-mode doesn't seem to be broadly used in the greater open source community whereas Markdown (or just plain text) CHANGELOG.md, NEWS.md, History.md, and others are far more common. There's surely personal bias at play, but I'm far more concerned with people keeping a changelog in the first place to worry too much about how exactly they do it. If Org-mode is what they go with, fine, but what we're facing right now is hordes of open source projects that people end up taking on as direct or transitive dependencies and which do not document their evolution in any meaningful way.

mianos 10y ago

Someone should send this to the guys who maintain the google internal apps like gmail and google now.

TeMPOraL 10y ago
Or Skype, which just tells you something like "we've updated your Skype application, which among other things means less bugs and improved performance".

exratione 10y ago

I'd argue that the goal of creating a good, useful changelog can be one of the forcing motivations to establish a working process for commit documentation and great, informative, useful commit messages. If that means git log gardening after the fact, then so be it, but good documentation (of history here) is always worth the work. The activities of programmer-archaeology are always made so much easier if you have a screed of history for each area of interest in the codebase. Sadly that's still rare, even in groups that do the necessary work to maintain their documentation for the current state of HEAD. There are many times when history matters, is relevant, and those who do not learn it are doomed to repeat it - or at the very least build elaborate theories to explain what happened in the past in order to understand how the present came to be where it is. The great changelog built on great commit history is probably hard to do outside of a small, focused group. On the other hand, the pull request process has emerged and developers have embraced that level of work, so it feels like it should be achievable.

olivierlacan 10y ago
I agree. Maintaining a changelog can be certainly be more difficult in large projects (although I don't think it has to be). I do think changelogs are a manifestation of the maintainers' care with regard to end-users. It signifies that they don't simply focus on the quality of the project itself but also how the project's evolution is perceived and understood by end-users and fellow contributors. It's strange to me that anyone would consider especially open source software as something so good and obviously beneficial that the archeology you mention would be a fact of life for end-users. It betrays a misconception about the value of software in a vacuum: without tests, code documentation, interface design, and change documentation (a changelog). The best algorithm is useless without proper tests verifying how it functions against real input; it's obscure without good documentation highlighting its quirks and design decisions, and if it evolves without clear explanations within a changelog then the changes in its behavior will remain mysteries to end-users as long as they don't go deep inside the code to understand how it worked before and how it works now. I've had to do this kind of programmer-archeology on numerous production dependencies (transitive or otherwise) in the past and the resulting frustration is very much the fuel that motivated me to make keepachangelog.com

skybrian 10y ago

This is fine for smaller, low-velocity projects, but tends to result in merge conflicts in high-velocity projects. An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.

derefr 10y ago
I don't see how; presumably a CHANGELOG should only be updated as part of release engineering, not during development. It's a document owned by whoever bumps the version number.
- bluejekyll 10y ago
  I find it easier to maintain one while you make the changes, thus I would see the issue being referred to.
- chrismorgan 10y ago
  Speaking in the context of an open-source project: Writing a changelog progressively is the only way you’re likely to end up with it being good. Consider the whole point of the “unreleased” section, too. If you put it off, you’ll just keep on putting it off, and when you finally do make a release you’re unlikely to put enough effort into the changelog. Your changelog will be better if you write it at the time of development, not release. To be sure, you’ll want to check over it at release time or even before then, but there’s no rule against amending the changelog at any time.
olivierlacan 10y ago
A common convention we showcase in the Keep a Changelog changelog itself (https://github.com/olivierlacan/keep-a-changelog/blob/604e382bf3a438613691405efb072769fde22e08/CHANGELOG.md#unreleased https://github.com/olivierlacan/keep-a-changelog/blob/604e38...) is to have an [Unreleased] section at the top of the changelog. It rarely conflicts with other branches of a project because it only becomes a version prior to or after a merge into the main branch (trunk/master/etc.). I'd agree this is an area we need to clarify for version 0.4.0 and forward.

kitsuneudon 10y ago

The changelog on a lot of popular apps on the Play Store has just become a place to promote stuff, not show off whats new.

bertr4nd 10y ago

I hope this is different from what this article is advocating, but I worked on a project that kept per-sub directory changelogs that were intended to track every commit to every file in a directory. Our tech lead basically had to nag everyone to write them, and it felt like a big waste of time (Note, this was not an open source project, and the article specifically speaks to OSS.)

olivierlacan 10y ago
Yeah, this is definitely not what I'm advocating. That sounds insane to me. Several contributors have pointed out that these conventions can be useful beyond the realm of open source so I think we've tried to make it a bit more general. It is definitely based on open source conventions though. An open source project like Rails has different components all developed within a single repository although they're packaged up independently for release. Each different component has a root level changelog that documents its changes and there isn't a centralized changelog for all of Rails. In some ways it's problematic because you can't see a merged changelog for all core components of Rails but it's also useful when you're only worried about changes to the ORM component since you'll only see changes pertaining to it within its own changelog. In my mind a changelog is a root-level concern for a single piece of software, regardless of how many isolated components it's composed of. Basic tooling should be able to centralize each changelog (as long as versions are synchronized, but that's another issue) and ideally you should be able to filter by sub-component. This is definitely not something we've created any guidelines for yet. So if you have any thoughts on the matter, feel free to suggest them: https://github.com/olivierlacan/keep-a-changelog/issues https://github.com/olivierlacan/keep-a-changelog/issues

kazinator 10y ago

Do not keep a ChangeLog; it is redundant w.r.t. your git commit messages and causes useless merge conflicts when you cherry pick, rebase, etc. Do use ChangeLog format for commit messages!

spb 10y ago
It sounds like you're confusing what the author is describing with GNU "Change Logs" (https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs https://www.gnu.org/prep/standards/html_node/Change-Logs.htm...), which track every source file change and are indeed redundant with `git log` (or any other version control system record). This is calling for more use of what GNU calls a "NEWS file" (https://www.gnu.org/prep/standards/html_node/NEWS-File.html https://www.gnu.org/prep/standards/html_node/NEWS-File.html), which is what virtually everybody else means when they say "changelog". Per the page itself: > Why can’t people just use a git log diff? > Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states. > As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.
- ChuckMcM 10y ago
  I tend to agree with both of these comments, that git commits are a very acceptable (and actionable change log) and that git log diffs are full of noise. That doesn't invalidate them as change logs though. I've got a command that will add everything that has changed in a directory tree except for ignored files, into a commit. And it is very helpful to write in the commit exactly what you're doing . You do this once a day and you've got an excellent log not only of how you have changed things but you can hop back to a previous commit and reset to a previous day. Now when it comes time to create a pull request ... Then you can go back and rebase and squash from the original start, and things into a commit history that is explainable and readable for the project. The only thing that would make this even more seamless if you could do a split-squash where you take a commit, "ungroup" it into its individual changes, then put the changes into their respective commits, and then squash those with the commits for what something should be at the end point.

edoceo 10y ago

This is right inline with a 'relnote' project I was working on. Mapping git logs to customer facing messages. Multiple commits/merges with terse engineer speak rewritten by English majors to concise sentences.

Twisell 10y ago

This project "visual changelog" usually blow my mind at every release. https://www.qgis.org/en/site/forusers/visualchangelog216/index.html https://www.qgis.org/en/site/forusers/visualchangelog216/ind... And this is exactly the opposite of a git commit only changelog. They put great effort in it so that everybody wait for it eagerly, and it might one of the reasons they got lots of sponsors and users donations.

dividuum 10y ago
Same with the Unreal Engine Release Notes (https://docs.unrealengine.com/latest/INT/Support/Builds/index.html https://docs.unrealengine.com/latest/INT/Support/Builds/inde...). Every time it is linked somewhere I just have to look at all the new shiny features despite not having any interest in using it at the moment.
- TeMPOraL 10y ago
  Holy hell! This is amazing! I just read both changelogs (QGIS and UE) and found them very interesting even though I'm not doing anything with either of them. I can imagine making such visual logs is much more time-consuming than just browsing through commit logs since last release and retyping commit messages in plain English, but the potential of such visual logs to actually get read and understood is much greater. My question is - is there any tool that one could use to quickly capture a few seconds of a selected region of the screen as a video/GIF? Preferably one that would subsequently allow to throw away some frames from the beginning and ending. Such a tool would speed up the process of creating visual changelogs quite a bit.
  - yeldarb 10y ago
    Yes, LICEcap is good for this: http://www.cockos.com/licecap/ http://www.cockos.com/licecap/
    - dividuum 10y ago
      On Linux there is recordmydesktop and its gui frontend gtk-recordmydesktop. I don't have a lot of experience using it, but a few tests worked as expected.

ashitlerferad 10y ago

The Debian advice for changelogs: https://www.debian.org/doc/manuals/developers-reference/ch06.en.html#bpp-debian-changelog https://www.debian.org/doc/manuals/developers-reference/ch06... https://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs https://www.debian.org/doc/debian-policy/ch-docs.html#s-chan...

orta 10y ago

Agreed, in the last few months I've been using Danger (http://danger.systems http://danger.systems) to ensure that the OSS projects I work on ( CocoaPods/CocoaPods, artsy/eigen, artsy/emission ) all have consistent Changelogs. Works out nicely.

dblock 10y ago

There's a beginning of an automation library for http://danger.systems http://danger.systems in this vein, https://github.com/dblock/danger-changelog https://github.com/dblock/danger-changelog.