Hacker News new | past | comments | ask | show | jobs | submit login
Keep a Changelog (keepachangelog.com)
137 points by vdfs on Aug 26, 2016 | hide | past | favorite | 45 comments



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.


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.


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.


Yes, LICEcap is good for this: http://www.cockos.com/licecap/


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.


The age of animated gif files is over. You want something that creates webm videos, like VLC or ActivePresenter.


Its not over until I can embed video in github markdown files. ;)


You can stop using github whenever you want to.



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.


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


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.


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.


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.


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.


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.


I'm aware of hundreds if not thousands of projects on GitHub alone using similar ways of documenting changes with CHANGELOG-like files and regardless of their size/popularity I'm not aware of the issues you both seem to be worried about.

Generally people edit changelogs after pull requests have been merged or as part of the pull requests themselves. It's far easier to figure out merge conflicts if and when other versions appended to the changelog simultaneously because all changelog entries are dated (or at least they should be) or at least versioned and contain plain text.

That said I agree that we should probably spend some time detailing common processes for editing and appending to a changelog in situations with concurrent branches being developed.


This is a real issue. I ask contributers to add a bullet at the top of NEWS.md and I frequently have to manually fix merge conflicts.

This is only a problem if you're handling multiple PRs simultaneously so your project has to reach a certain level of use before you'll see it.


Git does support custom merge "drivers" on a per file basis. For example: https://gist.github.com/seanh/378623


I wonder if it would be sufficient to set the changelog's merge strategy to union in .gitattributes.


I've tried this - it helps, but it's not a silver bullet. (And GitHub doesn't use it in PRs)


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.


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.


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


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


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


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


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


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


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


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


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


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.


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!


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.


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.


git commit's -v or --verbose flag allows you to see a diff of your currently staged changes so that sounds somewhat similar to your command.

I find that seeing the exact changes you're about to commit does lead to more detailed git commit messages, although the maximum length of most "properly" written commit message titles (50 characters) tends to hinder the quality of commit message titles as entries in a changelog. They're often very high level summaries of introduced changes and it's common for people to focus on the change at hand — not on its impact on end-users — when writing a commit.

Again, this all goes back to the intended audience for commit messages compared to change logs. If the end users of the projects you work on diligently read every commit in the project history, then I dare suggest you're in a rare and privileged situation. I don't expect end-users of most open source software to be satisfied with either the high-level nature of commit titles, or their minutia. This leads me to think that keepachangelog.com needs to gather more examples of the of changelogs I advocate for. It seems that a surprisingly small number of people have encountered them.

Rebasing and squashing commits to clean them up to be changelog-worthy does not solve the 50-character issue with conventional commit titles I mentioned above. It also doesn't solve for situations with collaborative pull requests or branches. That is, unless there's a clear process for squashing and rebasing being done by a single person at the very end of the project. I think it's more realistic to expect a single file changelog to be regularly updated (through an Unrealeased section) as changesets are being introduced prior to a release and to eventually update this same single file when the group of changesets is about to be released under a new dated version release.


> I don't expect end-users of most open source software to be satisfied with either the high-level nature of commit titles, or their minutia.

In my experience, they aren't. They want a top-level view of why/if they should upgrade.

In my dayjob, when preparing a release, we use tools to dump the git commit messages into the head of the CHANGELOG, then edit it back into user-facing text. We omit changes that are not user-facing (eg. 'gem you've never heard of upgraded to 0.4.4') and focus on changes they care about (eg. 'Redact credentials from URLs in a cached buildpack's output'). See for example our Ruby buildpack CHANGELOG[0].

We build our own binaries for buildpacks. So in addition, for our Github releases, we take the CHANGELOG entry and append a table of supported binaries and default versions[1]. These show up in the CHANGELOG only if we add or drop a core binary.

We work out of Tracker, so we link to Tracker stories, bugs and chores for every mentioned in the CHANGELOG or release notes.

[0] https://github.com/cloudfoundry/ruby-buildpack/blob/master/C...

[1] https://github.com/cloudfoundry/ruby-buildpack/releases/tag/...


Aw man, I've been fetching the output of "git diff --cached" into the buffer when committing, to see the darned diff.


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.


There a many valid places to use the word 'log'. Anything that you want to note can go in some kind of a log. A change log is a log of changes. Your users will want to see the changes that are relevant to them, and they vastly outnumber the developers who want to see a commit log.

Code may be read more than it is written, but it is not read far more than either. You really should have both logs: one detailed for development, and one for your users.


I never wrote that end users should be presented with change logs; of course, you give them release notes.

Release notes are not logs. They omit changes, and present selected changes in a different order. As soon as you have two sets of release notes for two releases in one file, then it's becoming a log: a log which captures sequences of release notes. I agree of keeping such a thing rather than giving end users just the notes for the current release.

In any case, developers should not be required to deposit any blurbs into any file as they are committing, regardless of its purpose and style.

Do go ahead and produce release notes, and then keep them in the repository. Do not mix code changes with changes to the release notes file.


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.


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.


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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: