
Keep a Changelog - privong
https://keepachangelog.com
======
boramalper
I think (a good) changelog is especially important when it comes to closed-
source software where you don’t have the opportunity to downgrade easily (from
Windows software to mobile applications).

For example if you visit the App Store now, you’ll see the many app
developers, especially the _big_ ones such as Twitter, Facebook etc., are
using the same changelog entry for every, single, update: “Thanks for using X!
To make our app better for you, we bring updates to the App Store regularly.”
The problem is, this doesn’t tell me anything about what to expect. No, I see
that I _shouldn’t_ have anything to worry about because the new features are
throughly UX-tested, and as an app end user there is not much to consider
anyway (it’s not a framework I’m using in production, right?).

The problem is, the changelog matters when Facebook removes messaging
functionality to push its users to their new app for some for-profit reason.
Changelog matters when your favourite app which has been free for the past
couple years have decided that it’s monetisable now and there are intermittent
ads in your feed. It matters when they think you don’t need a functionality
anymore and proceed to remove it, but you actually do.

I think changelog should be enforced far, far more strictly for closed-source
software, and _especially_ for those on App Store and Play Store.

~~~
olivierlacan
Couldn't agree more. It's been heartbreaking to see the spread of those rote
changelog entries on iOS specifically.

Although, meanwhile, large companies like Apple and Google have started
including surprisingly high-level and compelling release notes or changelogs
to end-users in things like Chrome and Keynote.

Smaller shops like Transit, Halide, Darkroom, and many others are going the
opposite direction of Twitter and Facebook by offering very detailed and
compelling (although sometimes a little too over the top) changelogs for their
major releases.

One thing I wish people did more, and I feel like I should carve out a section
about this on Keep a Changelog: explain exactly _what_ bugs were fixed. I know
discrete updaters are becoming more rare with auto-updates, but seeing a
specific bug that affected you specifically squashed in a release is perhaps
one of the greatest values of changelogs, especially in the case of open
source software but also with closed source apps.

~~~
yjftsjthsd-h
> on iOS specifically

I wish. It's rampant on Android, too; of my recently updated apps right now,
about half of them have release notes on the order of "bug fixes and
performance enhancements". Even Google does it on their big-name apps!

~~~
zingplex
I found that the changelogs on Android have never been that high quality to
begin with. This is probably because from a very early stage (version 3.3.11),
the Android Market automatically updated apps.

------
olivierlacan
Since, as okket mentioned, Keep a Changelog has been featured on HN before let
me give you... a changelog of what's happened in the project since the last
time: [https://github.com/olivierlacan/keep-a-
changelog/blob/master...](https://github.com/olivierlacan/keep-a-
changelog/blob/master/CHANGELOG.md#100---2017-06-20)

Version 1.0 was released introducing: a much cleaner website presenting the
guidelines in a more digestible way; 13 new translations; a semi-decent
versioning system to help synchronize translations; and a lot of
clarifications and updates based on feedback and conversations that occur
regularly within the project issues: [https://github.com/olivierlacan/keep-a-
changelog/issues](https://github.com/olivierlacan/keep-a-changelog/issues).

I know trying to get ahead of the torrent of critical comments is pointless
but let me summarize: yes, I know you think changelogs have been defined
before. But you know just as much as I do that most changelogs (or whatever
you decide to call them in protest) are terrible and not as helpful to
software end-users as they should be.

There's been a _lot_ of progress in the past 3 years alone in that regard.
It's nearly unthinkable for an open source project to not include a decent
changelog for each release. That's good. There are still a lot of smaller,
less known, or older projects that could be improved with some basic changelog
hygiene. If you're interesting in helping, please do, and if keepchangelog.com
can help I'll be glad.

------
simongr3dal
Here's hoping this becomes mainstream again.

The usual "Make sure to grab the latest update to get the greatest experience.
We bring you performance improvements and bug fixes every 14 days" or some
annoying joke about dusting code off, taking the trash out and fixing the
space-time continuum is getting pretty tired.

~~~
craftyguy
The most infuriating changelog lines are the ones that just say 'bug fixes' or
'enhancements' (or 'improvements'). Too many change logs have these lines.

~~~
bmalehorn
I have written exactly that kind of changelog. Let me explain why.

I write the changelog for a product. In fact I write _two_ changelogs - one
for engineers and one for customers.

Engineers:

\- [New Feature] Added ability to ___

\- Improved logging on ___

\- Fixed a memory leak on ___

Users:

\- [New Feature] Added ability to ___

Not every change can be explained in one sentence to users. Internal logging?
Memory leaks? You're speaking a foreign language. Those entries must be thrown
out when making the changelog for users.

Eventually, there comes a release when you have thrown everything out. What do
you write? "Bug fixes & enhancements".

~~~
_asummers
You could say something like "fixed stability in account management" or "fixed
crash issues across application, improving stability across board". I
sympathize with not wanting to go into more detail than would be generally
understood by the audience, but there's a large chasm between "bug fixes" and
that. If I was experiencing those bugs, I can now expect them to be fixed and
I'm now in a better spot if I see them again to say "hey you didn't QUITE fix
that in release X". If I see "bug fixes", I can't guess what happened in that
release.

------
okket
Previous discussions:

[https://news.ycombinator.com/item?id=12370119](https://news.ycombinator.com/item?id=12370119)
(45 comments, 3 years ago)

[https://news.ycombinator.com/item?id=9054627](https://news.ycombinator.com/item?id=9054627)
(43 comments, 4 years ago)

See also issues/pull requests in the repo:

[https://github.com/olivierlacan/keep-a-
changelog](https://github.com/olivierlacan/keep-a-changelog)

------
tmcw
As far as I can tell, the autogeneration of changelogs you can do with
standard-version [https://github.com/conventional-changelog/standard-
version](https://github.com/conventional-changelog/standard-version) and
commitzen ( [https://github.com/commitizen/cz-
cli](https://github.com/commitizen/cz-cli) ) fulfills the criteria Keep a
Changelog wants: right date format, clear notes for breaking changes, and no
unnecessary information from irrelevant commits. I've really liked using the
two for a variety of systems - the strict commit message formatting and
opinionated changelog generation means that the resulting changelogs are
pretty darn readable. But ymmv.

~~~
toyg
These are node-specific tools. Do you know of anything similar but generic?

Ideally, one would have something that can be connected to project-management
tools rather than github, e.g. Trello: when you mark a checklist or archive a
card, the title should go in changelog.

~~~
StavrosK
I would like something generic as well. I used to use semantic-release[1] but
it's a bit too Github-specific for my tastes.

[1]: [https://github.com/relekang/python-semantic-
release](https://github.com/relekang/python-semantic-release)

------
barking
He says not to use your repository commit messages as the source for your
changelog text. That's exactly what I do use.

I started doing this after reading "The Pragmatic Programmer" where it's
argued that the DRY principle should apply to everything including
documentation.

It starts with the bug tracker. So when entering something in that I'll also
add the text that I want to appear in the changelog for the user to see (these
lines will have a // at the start).

When a bug/feature is completed a commit is made and the text in the bug
tracker is the commit comment. If the commit comment has a line starting with
a // then that line will have another line inserted above it //Bug fix: or //
Feature:

Finally on building the distributable the changelog is constructed entirely
from the lines in the commit messages that start with //

~~~
pacoverdi
That's also what I do. When releasing a new version, I run a script/gradle
task/... that:

\- compiles all commit messages since previous version

\- filters unwanted messages (according to special tags)

\- groups them by category (fixes, enhancements, ...)

\- opens an editor so that a human can prettify the changes

\- appends the end result to changelog

\- updates version files

\- commit changes / git tag / etc

EDIT: formatting

BTW, I always have to set up those tasks myself. I'm surprised some kind of
standard tool does not exist. I guess everybody has their own preferences and
no standard really emerged...

~~~
cloverich
There are probably a lot of tools that do this. The conventional-changelog[1]
is one project, and it links out many others. AngularJS is a good example of a
project that's been using that style for quite some time. I ended up using
that as inspiration for my own tool (similar to yours) because as you mention,
a lot of the pieces can be idiosyncratic to the project, and it turned out to
be a relatively straight forward affair anyways. But if I were starting an
open-source (node) project today, I'd probably just use the standard-version
tools and forget about it.

[1]: [https://github.com/conventional-changelog/conventional-
chang...](https://github.com/conventional-changelog/conventional-changelog)

------
mherrmann
I view the Changelog as a sales tool: It shows how much work you're doing on
the project. I'm developing a cross-platform file manager and try to keep its
Changelog very visual [1].

1: [https://fman.io/changelog](https://fman.io/changelog)

------
stared
Open source projects are one things.

For customer projects it is somewhat rarer to have a decent changelog. Though,
I think that Blizzard is awesome at it:
[http://us.battle.net/sc2/en/game/patch-
notes/3-9-0](http://us.battle.net/sc2/en/game/patch-notes/3-9-0)

(see both new features, game mechanics balances and bug fixes).

------
buchanae
I wrote github-release-notes to help me stop being lazy about releases. It
generates a log based on github PRs. It's not a perfect solution, but it's a
place to start, and helps track down the work done and the comments made so I
can start writing better notes. A lot of times, the first comment of a PR is a
great source of information about a change made (what, why, caveats, etc).

[1] [https://github.com/buchanae/github-release-
notes](https://github.com/buchanae/github-release-notes)

------
JoshTriplett
This isn't a changelog, this is a NEWS or release-notes file.

Keeping a changelog in version control is an invitation for artificial
conflicts on every single commit. (There are ways around that, but better to
not keep a traditional changelog, since version control _does_ completely make
those obsolete.)

But keeping a NEWS file is an excellent practice. And when you send out a
release announcement, you can include the corresponding release notes for that
release.

~~~
exegete
Yeah, that's the GNU coding standard. Changelog is for developers and bug
hunters to see changes to the source. Version control probably takes the place
of that now. NEWS is for "user-visible changes worth mentioning".

[https://www.gnu.org/prep/standards/html_node/Documentation.h...](https://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation)

~~~
JoshTriplett
Many people and projects now use NEWS that don't have anything to do with that
particular coding standard.

------
fpgaminer
Seeing this my first thought was "Oh cool, so you format your git commit
messages in a certain way, and then this tool will automatically generate
changelogs for you."

... but it wasn't that (rather, just good arguments and suggestions).

And now I'm wondering if my first thought is a thing? And if so, how it has
worked out for users.

~~~
olivierlacan
People have created million and a half tools to tackle this problem. Just look
at the issues and you'll find a ton: [https://github.com/olivierlacan/keep-a-
changelog/issues?utf8...](https://github.com/olivierlacan/keep-a-
changelog/issues?utf8=%E2%9C%93&q=is%3Aissue+tool)

I've tried to refrain from endorsing tools because I feel like they risk
making it easy to avoid doing what I actually encourage: curating the notable
changes for a release with your mushy human brain for other mushy human
brains.

I know it's hard, but perhaps it's a good constraint.

The idea that you will have the forethought of knowing when writing a commit
that it'll be one of the notable entries in your future changelog seems a bit
far-fetched to me. And as I tried to explain, the purpose of a commit is not
the same as the purpose of a changelog entry, so there's definitely tension in
the re-use of copy there.

I get the instinct to automate everything. I'm just not sure this is something
that should be automated. Now, an assistive tool to help maintainers review
commits for missing notable changes within a changelog, that's something I
could get behind.

~~~
bendavis381
I think the issue with automation is it requires a cultural change for most
companies / projects. People are very used to small atomic commits and so it’s
hard to reduce the noise once parsed into a changelog. To make it work, you
need each commit to be as meaningful as a line in the changelog.

We use Phabricator and it’s default workflow, so have a clean linear git
history. Phabricator already requires strict formatting for any new diff
(title, description, testing, etc). It’s built into the culture of any org
using Phab to consider commits as meaningful entries in the history of the
project. So it would be very straightforward (technically and culturally) to
require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for
each commit and have yourself a automated and meaningful log.

~~~
anonytrary
> you need each commit to be as meaningful as a line in the changelog.

Not really, your changelog-from-git-log generator doesn't need to incorporate
every single commit. The vast majority of commits shouldn't be incorporated in
a changelog anyway, since fine-grained commits serve a different purpose. It
could incorporate, for example, version-change commits whose messages serve
the exact same purpose as changelog entries.

    
    
      git commit -m "VERSION 1.1.0 <user readable desc of changes since 1.0.0>"

------
sonnyt
Keep a Changelog is a great resource! I actually built a service inspired by
it. [https://onset.io](https://onset.io), check it out. :)

------
spondyl
I like to think MMOs can be idolised a little bit when it comes to changelogs.

Just check out these patch notes for Patch 4.0 of Final Fantasy XIV:

[https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c...](https://eu.finalfantasyxiv.com/lodestone/topics/detail/8937c86379b2124393409732025dac57f23839bc)

Is your average player going to read all this? Probably not but it's still
fascinating to see the amount of effort put in for every change, major or
minor!

------
mikecx
Not sure what the policy is on self-promotion but if you're using Rails, my
company wrote
[https://github.com/CatchRelease/stenographer](https://github.com/CatchRelease/stenographer)
to keep our team up to date on changes. It works by detecting [changelog foo]
in your commit message and detects deploys across environments.

------
nickjj
I really like reading hand curated changelogs. In a weird way, sometimes
reading a changelog can be more satisfying than using the new version.

------
acobster
This is great. I bookmarked this and will be referring to it consistently as I
roll out my first serious open-source project. Thanks!

------
hamtr
Writing release notes for a very active project is pretty hard and time
consuming. I can understand why large companies simply say "Bug fixes and
improvements" instead of "14 A/B tests that help us understand what to build"

I write release notes for Figma and it definitely takes a lot of time, is not
perfect, and becoming increasingly challenging.

------
crtasm
Orfox/Orbot on Android seem to have no changelog, anyone know who I could
nudge and/or assist to make one happen?

Orfox issues link on f-droid is 404 I notice now.

------
lalos
I find it rewarding to clean up my commits, add the work done on the
CHANGELOG.md and push the branch for a PR and move on.

------
RickJWagner
Hacker News paydirt!

I love it when I find something that directly relates to every day
productivity. Kudos to the provider.

------
anonytrary
Wouldn't proper use of `git rebase --interactive` make changelogs unnecessary?

~~~
okket
No. The commit history is for the developer perspective, the changelog is for
the user perspective.

As a user you don't want and need all the details what changed between two
releases. As a developer you absolutely need to be able to look this
information up.

~~~
opk
I've always thought of the term changelog as being the full list of every
single change for the purposes of developers. Back before we had git and used
CVS or patches it was necessary to track all changes and this was often in a
file named ChangeLog. User relevant changes go in release notes or (a NEWS
file if you follow GNU conventions).

~~~
okket
Changelog is a bit ambiguous, indeed. Release notes would be a more fitting
name, but also not ideal IMHO. If you want to know what was changed and when,
you need the commit history anyway. Also for bisecting.

I'd argue these days changelog and release notes are more interchangeable than
changelog and commit history. The 'NEWS' GNU-ism never really caught on, maybe
because news does not imply log/history.

