Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

raymii.org

Post reply on HN
Print view View original

41–50 of 127 posts

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#41

Post by ChrisMarshallNY »

My changelogs are pretty complete.

One reason might be that they are not automatically generated. I hand-edit each entry.

Sometimes, I copy and paste the changelog entry into the last commit of the release (but I make sure to have a short, succinct initial sentence, as that is what shows up in Git browser history).

The changelog may end up being a lot more "generalized" than the commit comments, though, as it's meant to be read by users.

I appreciate the kinds of changelogs that you usually get with developer tools, where they are like encyclopedias.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#42

Post by JimDabell »

joepie91_ wrote: post #33
mfDjB wrote: post #5

The reason these bigger apps just put "Bugfixes" and "Performance Improvements" in their changelog is because when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in. Doubly so when different users are receiving different experiences. The article says at the end:…

> when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in. This is a terrifying sentence to me, because what it implies but doesn't say outright, is that there's not a single person in the organization who actually fully knows what is being released. If there wer…

> This is a terrifying sentence to me, because what it implies but doesn't say outright, is that there's not a single person in the organization who actually fully knows what is being released. If there were, then they should already have this information!

It’s not the collection of the information that’s difficult, it’s delivering it to the user in an appropriate way when you use phased rollouts with feature flags.

The change log that the App Store presents to the user is static and identical for everybody. The changes that a user actually experiences are not. So you might have 0% of your users experiencing a certain feature when the release goes out, 10% a day later, 50% a day after that, and 100% at the end of the week. Or, if the metrics show a bad response, it might end up at maximum 10% seeing it, and then it dropping back down to 0% the next day.

Apple gives you a static text field to enter the change log information, with limited length. If you have ten different features to release, your users will all receive them at different times, and not all of them are guaranteed to make it out to everybody, how is a static text field supposed to deliver that information?

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#43

Post by JimDabell »

vbezhenar wrote: post #24
johannes1234321 wrote: post #4

With many apps an issue for changelog writers is that often behavior is tied to feature flags, which can be remotely enabled. Thus a new feature is rolled out in the app but only visible to some testers. Only after a while it's enabled for all users. Thus app release is independent from availability of a feature. That said "Bugfixes and performance improvements" is as useless as it gets ...

I wonder how those features pass Apple review? It's easy to disable those flags to get review passed and enable them later.

You provide Apple with login details when you submit your application. Just enable all the features in advance for Apple’s test account.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#44

Post by curryst »

maxerickson wrote: post #37
goldenManatee wrote: post #19

Earlier quoted context omitted.

There’s also a mitigating liability aspect to this. If you start providing minutiae detail, you may start revealing pretty big faults that have escaped to prod. People question the safety of your product and now you’re open to lawsuit or at least micromanaged by some unforgiving end-customers. To cope, you start to not fix certain problems so you won’t have to report the bugs or you start lying what the bugs were. I’…

Aren't the flaws the sources of the liabilities?

Sure, but most people accept that flaws are inevitable. It's not practical (or profitable) for most industries to produce totally flaw-free software.

If you can't stop the flaws, the next best option is to shield yourself from those flaws harming your financial well being.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#46

Post by zikzak »

bauerd wrote: post #22
christophilus wrote: post #18

Earlier quoted context omitted.

I prefer the detail. You could always make the first line: “bug fixes and performance improvements” with details following. Then people who don’t care can ignore the details, but people who do care can get an understanding of what the change is about. Deep understanding of a change is really helpful when looking through history or trying to make sense of why this particular line was changed, etc.

This is about app store changelogs, not commit messages

I have never understood "it's an app store" precludes an expander or link to details.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#47

Post by WesolyKubeczek »

goldenManatee wrote: post #19
CJefferson wrote: post #6

The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here) "On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we…

There’s also a mitigating liability aspect to this. If you start providing minutiae detail, you may start revealing pretty big faults that have escaped to prod. People question the safety of your product and now you’re open to lawsuit or at least micromanaged by some unforgiving end-customers. To cope, you start to not fix certain problems so you won’t have to report the bugs or you start lying what the bugs were. I’…

This explanation doesn't make me empathetic at all, and lousy changelogs are still lousy.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#48

Post by WesolyKubeczek »

cesarb wrote: post #20

The worst of these is the "Google" app. For over a year, every single new version has the exact same four-entry changelog, which translating from Portuguese is something like: "enhanced search page appearance; new doodles designed for app experience; off-line voice actions, available only in the USA; web pages opened directly within the app". I have the slight suspicion that most of the almost weekly updates to the "…

Let me guess: the most recent changelog is getting picked up for every new version.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#49

Post by SpicyLemonZest »

joepie91_ wrote: post #33
mfDjB wrote: post #5

The reason these bigger apps just put "Bugfixes" and "Performance Improvements" in their changelog is because when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in. Doubly so when different users are receiving different experiences. The article says at the end:…

> when you have many teams contributing to the software not only through actual code editing but also feature flagging what features go out on what release, rollback policies etc this becomes a nightmare to fill in. This is a terrifying sentence to me, because what it implies but doesn't say outright, is that there's not a single person in the organization who actually fully knows what is being released. If there wer…

Many applications are big enough that no single person can hold the full details of what’s being released in their head. If a release contains a hundred changes from a dozen teams, there’s no way a VP or CTO sitting on top can understand them all in any depth, so “performance improvements + bug fixes” may well be the full contents of the 30,000 foot view.

That doesn’t mean it’s impossible to produce more detailed notes for a big application, but it’s a pretty involved process basically requiring a “release note manager”, not something that happens by default.

Re: Lets talk about changelogs (how I loathe 'bugfixes and performance improvements)

#50

Post by julik »

goldenManatee wrote: post #19
CJefferson wrote: post #6

The problem is often the "bugfixes and performance improvements" are a list of 60 things, and for almost all users "there are less crashes and it is faster" is all they would want to know. How many users want to read (OK, possibly people here) "On some versions of glibc, the 32-bit specialisation of memcpy which used SSE2 instructions had a bug when the memory being copied crossed the 2GB boundary, so in that case we…

There’s also a mitigating liability aspect to this. If you start providing minutiae detail, you may start revealing pretty big faults that have escaped to prod. People question the safety of your product and now you’re open to lawsuit or at least micromanaged by some unforgiving end-customers. To cope, you start to not fix certain problems so you won’t have to report the bugs or you start lying what the bugs were. I’…

This is likely why useful and important details in changelogs are suppressed. Products where owners/managers value and emphasise transparency are much better at this, but it requires a specific culture. I mean - it does take guts to say "All media in the application could be downloaded without authentication by anybody on the internet. This has now been fixed."
Post reply on HN