Keep a Changelog

by vdfs • 10 years ago

137 45 10 years ago

mcescalante2• 10 years ago

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

olivierlacan7• 10 years 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-w...

mcescalante2• 10 years 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• 10 years 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.

olivierlacan7• 10 years 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• 10 years ago

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

TeMPOraL2• 10 years 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• 10 years 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.

olivierlacan7• 10 years 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• 10 years 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• 10 years 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• 10 years ago

I find it easier to maintain one while you make the changes, thus I would see the issue being referred to.

chrismorgan2• 10 years 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.

olivierlacan7• 10 years ago

A common convention we showcase in the Keep a Changelog changelog itself (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.

chrismorgan2• 10 years ago

Version control systems don’t do a good job of helping you out with things like this. They see “I’m looking for this text before and this text afterwards” and so if you have two paragraphs each inserting a paragraph of text in the same place, you won’t be able to merge the two of them—they will conflict.

I wish that you could specify merge behaviour on a file-by-file basis for something like Git, even as simple as “don’t worry about the text before when adding lines, just anchor it to the text after” which would equate to “append to section” in the earlier outlined case.

kitsuneudon• 10 years 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• 10 years 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.)

olivierlacan7• 10 years 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

kazinator4• 10 years 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• 10 years 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.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), 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• 10 years 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.

kazinator4• 10 years ago

If everyone else means "release notes" when they say "change log", why do the revision systems use the word "log" to refer to detailed revision change messages, I wonder. For instance the RCS $Log$ expansion keyword, not only "git log".

What is a "git log diff"? I get"

  $ git log diff
  fatal: ambiguous argument 'diff': unknown revision or path not in the working tree.

I'm using the following format for commit messages:

  Topic subject line, short exec. summary.

  Optional: one or more paragraphs discussing the
  "why", or any background information, how the
  issue was found, why it's significant, how it
  relates to something else, or what other changes
  is this change a preparation for and so on.

  * file1 (function1): This was done.
  (function2) That. Typical ChangeLog stuff.

  * file2 (function3): Bugfix here, and so on.

astrobe_• 10 years ago

It seems to me that the redundancy is more with issue tracking software. More specifically, have two-way references between the issue tracking software and the VCS.

edoceo• 10 years 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• 10 years ago

This project "visual changelog" usually blow my mind at every release. 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.

dividuum2• 10 years ago

Same with the Unreal Engine Release Notes (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.

TeMPOraL2• 10 years 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.

ashitlerferad• 10 years ago

The Debian advice for changelogs:

https://www.debian.org/doc/manuals/developers-reference/ch06... https://www.debian.org/doc/debian-policy/ch-docs.html#s-chan...

orta• 10 years ago

Agreed, in the last few months I've been using Danger (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• 10 years ago

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

Keep a Changelog

Related Stories