
Keep a Changelog - vdfs
http://keepachangelog.com/
======
Twisell
This project "visual changelog" usually blow my mind at every release.
[https://www.qgis.org/en/site/forusers/visualchangelog216/ind...](https://www.qgis.org/en/site/forusers/visualchangelog216/index.html)

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
Same with the Unreal Engine Release Notes
([https://docs.unrealengine.com/latest/INT/Support/Builds/inde...](https://docs.unrealengine.com/latest/INT/Support/Builds/index.html)).
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
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
Yes, LICEcap is good for this:
[http://www.cockos.com/licecap/](http://www.cockos.com/licecap/)

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

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

~~~
current_call
You can stop using github whenever you want to.

------
ashitlerferad
The Debian advice for changelogs:

[https://www.debian.org/doc/manuals/developers-
reference/ch06...](https://www.debian.org/doc/manuals/developers-
reference/ch06.en.html#bpp-debian-changelog)
[https://www.debian.org/doc/debian-policy/ch-
docs.html#s-chan...](https://www.debian.org/doc/debian-policy/ch-
docs.html#s-changelogs)

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

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

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

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

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

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

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

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

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

------
mcescalante
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
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...](http://olivierlacan.com/posts/logging-changes-all-over-the-world/)

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

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

------
kazinator
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
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...](https://www.gnu.org/prep/standards/html_node/Change-
Logs.html#Change-Logs)), 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
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.

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

~~~
jacques_chester
> _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...](https://github.com/cloudfoundry/ruby-
buildpack/blob/master/CHANGELOG)

[1] [https://github.com/cloudfoundry/ruby-
buildpack/releases/tag/...](https://github.com/cloudfoundry/ruby-
buildpack/releases/tag/v1.6.22)

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

