Ask HN: Do you value Change Logs? | Hacker News Reader

Ask HN: Do you value Change Logs?

6 pointsNadya9 comments

I'm a stickler for change logs. I think they are a very important form of documentation of a project.

However, I've noticed that many projects do not maintain a very precise Change Log. Do most people not value them? Am I the only person who reads every single item in the Change Log before deciding to upgrade software?

Largest Pet Peeve

My biggest pet peeve is when the Change Log mentions "and other fixes" or "Misc. Bug Fixes" without a link to any further details. This issue is compounded when the project isn't Open Source/hosted on GitHub - so looking through Closed Issues isn't an option.

View on HN

As I think a lot of the people who tend to respond to these kinds of things are people who take up pitchforks over changelogs, and everyone else is like "engh, changelogs: boring conversation", I feel like it might be my duty to get over my initial reaction of "engh" and explicitly say "no". (I also happen to have a few minutes to kill as I need to wake myself up more while I'm waiting for someone else to finish something so we can go get lunch.)

I use changelogs for libraries and tools, but I certainly don't use them to decide whether or not to upgrade something... the things that are most important are often the one line fixes that no one really ran into or characterized well but when someone came across them was like "wow, I can't imagine how this ever worked before". I will decide whether or not to upgrade based on tests: if it doesn't work, then I don't upgrade; if it works, then I upgrade.

For apps, or minor little things, the idea that people care about changelogs is just strange to me: people use websites constantly that just kind of change in minor ways and the world doesn't end. The Facebook app on my phone automatically updates, and I know they send a new build of whatever they have to Apple every week whether they have major new stuff or not. Their changelog is forever essentially "we push new stuff every week, hopefully it will make you happy".

And, strangely to me, because it is an app and not a website, some people seem upset at this and want a better changelog. It seriously has made me prefer making websites and server-side components to client-side stuff, as people never ask me to do the extra useless-for-most-normal-users work of maintaining a changelog if I make a website, yet a tiny extremely-vocal set of people occasionally complain about changelogs if you make the mistake of writing software they install.

Thank you for taking the time to respond for precisely the reason you mentioned in your opening paragraph.

The one-liner would be included in the Change Log. I have a highly relevant example from the Runescape Game Client that happened today! Language selection was broken for the Mac version of the client. Users were unable to choose German/French/Portuguese worlds because of this.

A short fix was added to remedy this problem. But 99% of the users will never know this problem was fixed because Jagex doesn't maintain a public facing change log. Only a short "New:" for the most recent change.

Many Mac users who want to use the client but were prevented by being unable to change their language will never know once the next client update happens and the "New: Fixed Mac language selection" is removed. The fix was only mentioned by a Jagex employee on an infrequently browsed forum, where one day even the post will be lost once it goes past Page 50 (nothing is archived).

This is a scenario where a maintained Change Log (and public awareness of updates) would be highly beneficial to users.

The practice of tests has not caught on for all software - and more complex software often lacks pass/fail test builds for the public (eg: where are the tests for Photoshop?)

For apps - not everyone has unlimited data plans. So many people turn off automated updates. Data limits still exist at home for many non-U.S. users, so downloading updates on WiFi also isn't an option. Frequent updates (especially frequent, large updates) are annoying and prevent users from using an app due to data limits.

Due to said data limits, many people will only update when an update brings something beneficial. A useful feature, vastly improved performance, or important security fixes. Otherwise why waste the data?

>yet a tiny extremely-vocal set of people occasionally complain about changelogs if you make the mistake of writing software they install.

Change logs help developers too. Especially for open source projects [0] but also for internal projects. I'd argue it is less useful when the project is maintained entirely by a single person, as they will be aware of all changes they have made. However the moment there are 2 or more people working on the project, a change log becomes a useful asset for squashing bugs and keeping everyone up-to-date on important changes and deprecation changes of larger projects.

[0] http://keepachangelog.com/

In any well-maintained project, you compile a list of bug fixes and added features into a release notes text. See f.e Misc/NEWS in Python. More detailed than that, I don't think is necessary. As a user I'm just not interested in who fixed what (or reported the bug) and when they fixed it. There is always "git log" or "hg log" or "svn log" to fall back to if you want to investigate the history in detail.

I deeply value Change logs. I have the same pet peeve when I read things like "other misc. fixes" etc. If you have to write that, you might as well not write anything.

I love Change logs where it explains what issue was fixed or if a new enhancement/requirement was implemented and bonus points if it mentions the actual source files added/edited.

Essentials for your users and a fast summary of what happened in every release, changelogs should be maintained with the same care we devote to write clear commit messages.

I love changelogs. I choose programs based on how good their changelogs are. If someone made a program that just generated random changelogs, I'd probably use it.

Now I'm imagining the change log for a program that generates two random change logs and then creates a change log of the change logs. Forever.

  Step 1: Create two random change logs m and n
  Step 2: Create a change log that shows what changed between Change Log m and Change Log n
  Step 3: Create a random change log n+1
  Step 4: Create a change log that shows what changed between Change Log n+1 and Change Log n
  Step 5: Goto Step 3

There's a twitter account which pulls weird changelog entries and posts them

https://twitter.com/TheStrangeLog

I read changelogs for well maintained projects - I particularly love AngularJS's changelog, it is detailed and links to the commit each change is associated with

Reply on news.ycombinator.com