[HN Gopher] Lets talk about changelogs (how I loathe 'bugfixes a...
___________________________________________________________________
Lets talk about changelogs (how I loathe 'bugfixes and performance
improvements)
Author : jandeboevrie
Score : 179 points
Date : 2021-01-02 11:53 UTC (11 hours ago)
(HTM) web link (raymii.org)
(TXT) w3m dump (raymii.org)
| awinter-py wrote:
| > probleemoplossingen en prestatieverbeteringen
|
| love 'bugfixes and performance improvements' in dutch
| magoon wrote:
| What it takes to get through app review
| enra wrote:
| As a startup we write fairly detailed changelogs weekly [1]. For
| us it has been a major way to communicate all the new features
| and fixes as they come available to users. It's also a good way
| for the team to celebrate their accomplishments. I was surprised
| to learn it also had helped with investors and generally
| marketing.
|
| Usually the person who was a major contributor to the highlighted
| feature of the week writes the changelog and then we look through
| our PRs to add anything that could be interesting. We don't
| include things like "migrated x" "upgraded library x" if there is
| no visible benefit for there.
|
| Wrote about the lessons here: https://link.medium.com/9YuBV3dUIcb
|
| 1: https://linear.app/changelog
| nudgeee wrote:
| One of the reasons larger apps post unhelpful changelogs like
| these is because they probably run a feature flag/experimentation
| system. It is a backend driven system that allows app developers
| to remotely switch on and off features and code changes. This is
| really useful when rolling out updated features, you can roll it
| out gradually, eg 1%, 5%, 10%, 100%. Roll out a new feature 1%
| and notice its crashing for a subset of those users? Roll back
| the flag so users see the old UI and fix the problem for next
| release. It's better than updating a feature for all and having
| it crash for everyone (yes, even with testing sometimes bugs
| sneak through, especially when you have millions of users).
|
| It also allows app developers to bucket users in groups and A/B
| test experiments on users to see what works best. It would not be
| uncommon for the larger players (Microsoft, Google, Facebook,
| Pinterest, Uber, Spotify, etc) to have 100s or 1000s of
| experiments running concurrently. It also decouples rolling out
| features from App Store releases.
|
| Having said that, I also hate generic changelog messages and not
| defending the practice. If new features are to be launched with
| the build, write it in the changelog and add "(rolling out)" or
| "(coming soon)" next to it.
| Rockslide wrote:
| > If that is all you're going to put there, then just leave it
| blank.
|
| Well, I would love to. Unfortunately neither Play Store nor App
| Store allow you to do that... so "bug fixes and performance
| improvements" it is, 99% of the time.
| TrianguloY wrote:
| I also have automatic updates off and I really like checking
| changelogs to know what new things I can play with.
|
| And I don't mind reading 'bugfixes and performance improvements'
| ... but only if that's really what the new version is about. I
| like changelogs, but even for me a 'we fixed an issue where if
| you enter a 1025 characters text into the title textbox and press
| back twice while rotating the phone the app closes' is probably
| too much, but if you added a new option to increase the text size
| please say it, I don't want to check all the settings screens
| each time each app updates, and more often than not someone tells
| you 'hey, aren't you using this option?' No, no I wasn't, because
| no one told me.
|
| Are you a big company and you have automated updates? Why not
| have an automated checklist of changes too? I'm sure you have a
| 'roadmap list', so use it.
| [deleted]
| recrudesce wrote:
| As a tech person, I don't care.
|
| Most general users of apps on phones wouldn't give an absolute
| crap if you "fixed a buffer overrun in the X function", because
| that means nothing to them. If they read that you've made
| performance improvements, then great they can continue to play
| Candy Crush but not have it crash so often. They won't CARE that
| you "optimised the use of the strcopy function" or some crap like
| that.
|
| Remember the app stores are targeted towards consumer users of
| phones, not tech people that live on Hacker News websites.
| jrootabega wrote:
| In an "app store" context, the apps don't serve you; you just
| generate content/engagement for them. The apps you're looking at
| don't WANT you to be informed because you might choose not to use
| them. These notes are just a formality standing in for forced
| automatic updates. Spotify on Google Play is particularly
| insulting. They basically tell/shame you that you should just
| always update without caring about the changes.
| coldtea wrote:
| > _In an "app store" context, the apps don't serve you; you
| just generate content/engagement for them._
|
| This is a non-sequitur.
|
| There are all kinds of apps in an "app store" context, and the
| apps I use serve me very well, thank you. I also don't generate
| any "content/engagement" for any of them.
|
| Whether apps have good changelogs or not is also not a factor
| of whether the apps are in an app store or not.
|
| You maybe meant to say "social apps" as opposed to "app store"
| apps.
| jrootabega wrote:
| I guess I'm focusing on the ones at the top of the food
| chain, and the what I think is the predominant relationship
| in app stores, not necessarily the social ones. Eg the
| Microsoft ones in the article
| baby wrote:
| That was not really interesting, so I'll start a related thread:
|
| - why is performance often favored instead of improving,
| refactoring, documenting, simplifying, etc. And how can we change
| that?
|
| - why are bug fixes so hard to track? Often developers fix
| something without marking it as a bug fix. And how can we change
| that?
| kevin_b_er wrote:
| Because you aren't meant to know what the changes are, just
| consume.
| jka wrote:
| As with many others here no doubt, I spent a lot of time in 2020
| viewing diffs between library versions, reading changelogs, and
| tracking upstream bugs/features.
|
| Although I'll try to resist going on too much of a pro-FOSS rant,
| the change audit process is much easier for open source projects
| since you can read not just the changelog entries, but also the
| corresponding code to verify the claims.
|
| That helps with various things including developer trust - it
| helps you determine whether a project and authors use test
| coverage to reproduce bugs and prove their fixes, whether
| performance improvements are measurable, whether there are risky
| side-effects to look out for, and so on.
|
| Increasingly I think that these kinds of 'software due diligence'
| should become part of recommended software engineering workflows,
| and that makes me wonder whether some of the repetitive aspects
| can be automated.
|
| A genuinely user-focused, trustworthy app ecosystem would, I
| think, allow some of these 'change audit' processes to be visible
| to users so that they can make informed upgrade decisions, and to
| create a marketplace incentive for upgrades to be reliable.
| einpoklum wrote:
| It is much more likely to see decent Changelogs on Free Software.
|
| (For many reasons, but including: "We added a new backdoor to
| satisfy government mass-surveillance program requirements.)
| [deleted]
| xyzelement wrote:
| I just looked at WhatsApp (one of his examples) and it has a
| detailed "what's new" in both the Apple and Android app stores
| that's listing three high level features.
|
| Sounds like the screen shot he took in September really was a
| bugfixes and performance release.
|
| So it sounds like these apps (at least, WhatsApp) follow a wise
| policy - tell the users what has changed that matters and don't
| drown them in irrelevant information.
|
| I had the same policy for my teams - tell users 4-5 new
| features/changes to workflow they are going to see and for g-d's
| sakes, do not drown that out by listing 400 irrelevant
| infrastructural changes we happen to be pushing out.
| henkdevries wrote:
| If an app is good enough, developers and managers and "agile
| coaches" and such don't stop, they start doing busywork. It looks
| like they're working and progressing, but all they do is scare
| users away with by removing features, breaking workflows and more
| horrible stuff. You're just making money for the shareholders,
| nothing more. They don't care about users...
| dvfjsdhgfv wrote:
| In the case of many popular apps, it's a bit more than that:
| they're actively fighting what they perceive as bad actors,
| that is people trying to use their app not as intended, using
| their protocol outside of the official app and so on. In this
| case they have nothing to gain by describing the changes in
| more detail in the changelog.
| joshspankit wrote:
| Every time I see "bugfixes and performance improvements", I
| immediately assume that they've installed more tracking code.
|
| Just like when I see "50% less sugar", I immediately assume they
| replaced sugar with chemicals.
| [deleted]
| cesarb wrote:
| 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 "Google" app do not have
| these four changes... for that app, "bugfixes and performance
| improvements" would actually be a _better_ (more correct)
| changelog.
| WesolyKubeczek wrote:
| Let me guess: the most recent changelog is getting picked up
| for every new version.
| ChrisMarshallNY wrote:
| 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.
| thomaspaulmann wrote:
| For early-stage startups, writing changelogs is also a great way
| to close the feedback loop with their user-base. We write
| detailed release notes at Raycast [1] to highlight feedback that
| we addressed. This way our users see that we care about their
| feedback and feature requests.
|
| [1] https://raycast.com/changelog
| johannes1234321 wrote:
| 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 ...
| vbezhenar wrote:
| I wonder how those features pass Apple review? It's easy to
| disable those flags to get review passed and enable them later.
| mackey wrote:
| It depends on the feature. For things that involve material
| changes to your app or a feature that you don't want Apple to
| be surprised about, usually you will include user credentials
| in your submission that have that feature enabled and give
| them a heads up. If's a smallish feature, you don't usually
| sweat app review. It's obviously not a perfect system.
| robotnixon wrote:
| I'm pretty sure that's what Fortnite did right before they
| got kicked out of the App Store.
|
| Before my company implemented IAP in a few of our apps we did
| the same thing, but decided the risk was too great. Getting
| rejected is one thing, but getting your account terminated is
| obviously a much bigger deal.
| JimDabell wrote:
| You provide Apple with login details when you submit your
| application. Just enable all the features in advance for
| Apple's test account.
| olivierlacan wrote:
| This is precisely why I started https://keepachangelog.com/ many
| years ago. Release convenience shouldn't come at the cost of
| properly communicating about notable changes for software users
| (whether developers themselves, or software consumers).
|
| Instinctively, developers reach for automation to solve this
| problem but this is an editorial problem for most software. Code
| changes very rarely map to notable changes for your intended
| audience. Even with rigid system like conventional commits, you
| can't entirely automate proper human-focused changelogs and
| release notes.
|
| You're going to have to clean things up and editorialize if you
| really care for your software users to understand what notable
| changes are included in a given version release.
|
| If you can't think of any, maybe you're releasing too often. If
| it's impossible to tell things apart because there are so many
| changes as another commenter pointed out, I think you have a way
| bigger problem.
| mfDjB wrote:
| 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: "You see? Not that hard right?". It
| is that hard in bigger organisations.
| 0xbadcafebee wrote:
| Which is a good indication that the organization actually has
| no idea what the heck is going into the update.
| damnyou wrote:
| Assuming there are good rollout and incident review processes
| in place, this isn't much of a problem in practice.
| toast0 wrote:
| If you're shipping a mobile app with client side code (so,
| nearly all of them), there is no good rollout process.
|
| You can't ship a quick update with Apple, because review
| isn't quick. Users who upgraded soon after release will be
| stuck with something broken until the new version is
| available.
|
| You can usually ship quickly with Google, but users are
| slow to upgrade, but may have caught your first one, and
| not get your second one for some time.
| damnyou wrote:
| I'm talking about feature flag based rollouts, which
| don't involve going through Apple or Google.
| coldtea wrote:
| > _The article says at the end: "You see? Not that hard
| right?". It is that hard in bigger organisations._
|
| The size of the organisations is not important, as is the size
| of the team working on the particular feature/app.
|
| Apple is huge, for example, but eg. Logic Pro has great
| changelogs.
|
| We also see huge apps (with large teams) do better than than
| small apps (with much smaller teams). It's more about
| bothering/caring than difficulty.
| mackey wrote:
| Apple has a much more traditional engineering structure and
| traditional release cadence though. A lot of the "worst
| offenders" of these types of release notes are structured and
| work much differently. They release updates 1-2 times a week,
| sometimes release features weeks after the code has shipped
| to users, and sometimes in stretched out rollouts.
|
| They say there if there is a will, there is a way, so in a
| sense I agree that these companies probably could do
| something about it if they really wanted to, but I also don't
| think it would be easy, and considering how few people
| actually look at release notes, I am not sure the investment
| is worth it.
| damnyou wrote:
| Logic Pro doesn't have server-side feature flags.
| coldtea wrote:
| Many apps don't have either, and they have shitty
| changelogs still...
| damnyou wrote:
| As far as I know all the big apps the OP is complaining
| about have server-side feature flags.
| joepie91_ wrote:
| > 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 were, then they should already have this
| information!
|
| Honestly, if you don't have a release manager with a 30,000
| foot view of the operation, you probably have bigger
| organizational problems than "it's hard to know what to fill in
| on the app store's release notes".
|
| This is how retrospectives on supply chain attacks start,
| basically.
| toast0 wrote:
| > there's not a single person in the organization who
| actually fully knows what is being released.
|
| Sometimes there is, but as siblings point out, it's difficult
| or not cost effective to distill this information into an app
| store changelog blurb.
|
| More often (in my opinion), it's the terrifying situation you
| describe. Nobody know what the heck is going on at an overall
| level. Which can work surprisingly well, but often means
| efficiency (network, memory, cpu, disk space) is very hard to
| come by.
| SpicyLemonZest wrote:
| 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.
| damnyou wrote:
| No. what it signals is that app releases are decoupled from
| feature releases. Of course people know when a new and
| important feature is being released, it's just completely
| independent of when the app store update goes out.
| JimDabell wrote:
| > 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?
| temac wrote:
| It is bugfixes or performance improvements about things that
| exist, though.
| hashkb wrote:
| Difficulty of task never excuses doing a lazy job. Especially
| if you hope people will pay you.
| fwip wrote:
| If it's worth doing, it's worth doing half-assed.
| CJefferson wrote:
| 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 now use our
| own memcpy"
|
| Or "Changed some internal lists to be only be sorted when they
| need to be rather than eagerly sorted whenever elements are
| added, which speeds up start-up time".
| degenerate wrote:
| A lot of people here would like this level of detail, actually.
| But general apps are intended for the general population, which
| is why big orgs go for the minimum watered down version. It's
| more work and overhead if they confuse their users.
| pc86 wrote:
| I think the author of the article brings up a good point
| regarding this, though. If you're a non-technical user, you're
| not going to read it at all. You might update, you might not,
| but you're not going to look through the list of changes.
|
| If you're a technical user, you know it's unlikely that update
| == "more crashes and slower load times" so saying the opposite
| isn't helpful, and a list of things _might_ be helpful.
|
| So as a user of an app you probably fall into one of 3(ish)
| categories:
|
| 1. You read the changelog and something is relevant to you.
|
| 2. You read the changelog and nothing is relevant to you.
|
| 3. You don't know what the changelog is.
|
| Listing the bugs that are fixed helps some of these groups.
| "Bugfixes and performance improvements" is a given, and helps
| no one.
| grayclhn wrote:
| Even when I'm in group 2 and don't want to read every update,
| I'm reassured by the fact that users in group 1 can find
| relevant information. I also sometimes move from group 2 to
| group 1 when I need to track down what version introduced
| something that's just now causing me problems. :)
| brewdad wrote:
| I tend to fall in either 1 or 2 depending on whether I've
| been bitten by a specific bug and need to know if it has been
| fixed.
|
| The worst changelogs are the ones that say "Performance
| improvements and bugfixes" only to find out the entire user
| interface has changed after updating.
| a1369209993 wrote:
| > If you're a technical user, you know it's unlikely that
| update == "more crashes and slower load times" so saying the
| opposite isn't helpful, and a list of things might be
| helpful.
|
| Umm, no; if you're a technical user, you know it _is_ likely
| that update == "more crashes, slower load times and useful
| features breaking or disappearing entirely", regardless of
| what the changelog says, because you've observed exactly that
| happening with eg your webbrowser or image editor.
|
| > "Bugfixes and performance improvements" [(]is a given[)],
| and [(]helps no one[)].
|
| Well, you're half right.
| toast0 wrote:
| > If you're a technical user, you know it's unlikely that
| update == "more crashes and slower load times" so saying the
| opposite isn't helpful, and a list of things might be
| helpful.
|
| It's precisely _because_ an update might bring more crashes
| that I 'd like to see what changed.
| johnisgood wrote:
| Look at SBCL's changelogs, I like those. I definitely would
| like that over "there are less bugs and it is faster".
| viceroyalbean wrote:
| Doesn't have to be coverage of every minute detail down to the
| implementation, but a rough outline of at least the most
| significant changes seems like a good middle ground. On several
| occasions I've revisited a feature (or even an entire
| application) upon seeing that an issue I've had has been
| addressed in the changelog.
| christophilus wrote:
| 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.
| bauerd wrote:
| This is about app store changelogs, not commit messages
| johnisgood wrote:
| So it is more important than ever because there are no
| commit messages you could go through, right?
| zikzak wrote:
| I have never understood "it's an app store" precludes an
| expander or link to details.
| lallysingh wrote:
| Two reasons:
|
| + Customers will often have no understanding of what
| you're saying, but still click the link and give low
| reviews for it's content.
|
| + More stuff the the app store review team to refuse
| publishing an update for.
| goldenManatee wrote:
| 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'm not
| so sure it's on net a useful direction to be quite that open.
| wbl wrote:
| Has there ever been a lawsuit in which a company was held
| liable for bugs despite the usual disclaimer?
| Nextgrid wrote:
| Let's stop condoning covering up incompetence.
|
| If you fuck up, admit to it, fix it and learn from it.
|
| If you fuck up bad enough that someone had a good case
| against you then you should make them whole and use the
| opportunity as a wake-up call to make sure this never
| happens.
| maxerickson wrote:
| Aren't the flaws the sources of the liabilities?
| curryst wrote:
| 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.
| pc86 wrote:
| Having a changelog does not make you more open to
| lawsuits.
| pjc50 wrote:
| Are there _ever_ successful software product quality
| liability lawsuits?
| 1vuio0pswjnm7 wrote:
| In the US, a software license cannot limit liability or
| damages arising from physical harm. Think of an instance
| where software is the cause of physical harm.
| WesolyKubeczek wrote:
| This explanation doesn't make me empathetic at all, and lousy
| changelogs are still lousy.
| WalterBright wrote:
| Back in the 80s when I was starting out in the compiler
| business, I thought it would be a good service to include
| with it a list of the known bugs.
|
| It didn't take long before a magazine reviewer did a compiler
| roundup and simply printed the bug list as his "review". It
| was a disaster for my business.
|
| It took me 20 years to get over being brutalized by that and
| make the bug list publicly available again.
|
| https://issues.dlang.org/
| julik wrote:
| 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."
| zbrozek wrote:
| It's important to list what bugs you fixed. You can do fancy
| things like group your changelogs under headings if you want to
| make it easier to maintain focus for different audiences. A CAD
| tool I use, for example, lists every single bug fixed and
| references a ticket number with each. This is extreme, but much
| better than the opposite extreme.
|
| It lets me know when I can stop using workarounds, or alert me
| to landmines I've unknowingly tripped and lets me go back to
| verify old designs.
|
| Regardless of who the user is, a changelog is supposed to tell
| you what actually changed. If you're not going to do that,
| don't bother having one. But if you don't bother writing one,
| I'm not going to bother updating to the new version. From my
| (the user's) perspective there's no incentive to do so unless I
| know what I'm getting. There could be anything in there, so
| I'll stick to the devil I know.
| jandeboevrie wrote:
| Hehe I'd be happy to read such a changelog
| sltkr wrote:
| I doubt you would. A large app each would have hundreds of
| changes like this. It would get pretty boring after the first
| dozen or so.
| gregmac wrote:
| I think the key is describing the user-facing effects and
| impact. This means knowing your users (are they developers, IT
| or highly technical? Do they automatically or manually update
| quickly, or do they take time to evaluate before rolling out
| updates?). It's a way to convey continuing value to users and
| convince them it's worthwhile to keep paying, and get motivated
| to get the update.
|
| I'd try to change what you wrote to something like:
|
| "Fixed out-of-memory errors on some 32-bit systems"
|
| "Improved startup time for configurations with lots of items"
|
| This makes it easy to gauge if this update is important to get
| installed ASAP, such as fixing something they've experienced or
| are likely to experience.
|
| Grouping "several UI fixes" or "performance improvements" is
| usually fine, but I tend to call out something like "fixed UI
| bug where a network error could result in changes not being
| saved with no warning" or an issue that a sizable chunk of
| users had reported.
|
| Doing this well takes time, though, as you have to synthesize
| the internal ticket summaries, PRs and/or commit messages and
| reword almost everything. This is understandable for open
| source or free/indie apps, but for subscription/"enterprise"
| software it's definitely one of the differences between "great"
| and merely acceptable (or worse).
| WalterBright wrote:
| > Doing this well takes time
|
| For us, not that much time, as everything goes through the
| bug tracker (even enhancements) so it's mostly a copy-pasta
| job. When I submit a fix for a bug, I'll often edit the
| subject to accurately reflect what the problem actually
| turned out to be.
| leesalminen wrote:
| > but for subscription/"enterprise" software it's definitely
| one of the differences between "great" and merely acceptable
| (or worse).
|
| I couldn't agree more.
|
| I tried writing more informative but easy to digest release
| notes when a couple noisy users mentioned at a trade show
| that they wanted to know more about our bug-fixing efforts.
|
| To my surprise, we got a huge volume of communications from
| our users that they loved our new release note style and to
| keep it up.
|
| It takes us about 1 hour / release to write. We release small
| changes weekly and large changes monthly to about 1mm MAUs.
| mkr-hn wrote:
| See Reaper (the audio thing) for the opposite extreme. The
| changelog lists _everything_ , so sometimes you miss
| significant new features because they don't make a big deal
| about it.
|
| https://www.reaper.fm/download.php#whatsnew
|
| They put a whole notation editor in and didn't say anything
| past the item in the changelog. Most tools like it have a
| notation editor, but it's a $300 addon instead of a free update
| to the standard $60 package.
| alexcroox wrote:
| I automate the app deployments for our team and "bugfixes and
| performance improvements" is the changelog because it's totally
| automated on release. Yes the automation could grab something
| from the commit logs but I'm not confident I'd want to expose
| some of our commit messages. Also recent versions of iOS have
| further hidden away the update ui making it very hard to find for
| most users, so why bother taking the time to add them manually
| when 99% of your user base will never see them?
| Kudos wrote:
| You can maintain a file with the current/next changelog in your
| vcs and pull from that. Works with automation, but is still
| curated.
| kingosticks wrote:
| I think I'd argue it's not "totally automated" unless skipping
| the changelog generation step was the intention. In which case
| no need to justify that with any reasons, that's your (valid)
| choice to omit some documentation. We used to maintain our
| "customer-facing" changelog as we merged the associated code
| but that did create work when trying to release and finding
| some people had forgotten to provide an entry, which ultimately
| reduced release frequency. So now we don't include a changelog
| in the release itself, we create it after the fact and it's
| more of a "living" document hosted online (having to create
| another new release just because of dumb mistake in your latest
| changelog is really annoying). For those that are really
| interested, they can check the commit logs. For those less
| interested, they can wait for the online changelog to be
| written. It's likely they'll only have to wait a few minutes.
| Obviously the former is easy for open-source projects. I'm not
| convinced our new way is better yet but I'm willing to wait and
| see if the release frequency improves.
| twright wrote:
| One time I wrote simply "bug fixes" for an app update and it got
| rejected because the description was too short. I changed it to
| something more in the lines of "bug fixes and improvements" and
| it got accepted. I generally like writing changelogs for users
| but I also wonder how many people have automatic updates on and
| never read them.
| CM30 wrote:
| Yeah, it is nice to know what the actual changes are, rather than
| a vague 'fixes were made' statement. Nintendo's update logs for
| games have to be some of the most hilariously vague in that
| regard, with many of the updates being just:
|
| > Several issues have been fixed to improve gameplay experience.
|
| But at the same time I guess I can see why companies and project
| creators don't go into more detail. Maybe the actual bugs fixed
| were so weirdly technical that most users wouldn't understand
| them at all, or care (if the user hovers over this button for
| 1/300th for a second, there's a 0.0001% chance their next message
| might not save properly). Maybe they (perhaps sadly) don't
| remember what exact things they fixed, since they fixed so many
| bugs.
|
| Either way some more detail would be nice for those that do care
| about this stuff.
| rubyist5eva wrote:
| > Nintendo's update logs for games have to be some of the most
| hilariously vague in that regard
|
| On the flip-side, the changelogs for Super Smash Bros Ultimate
| and Splatoon 2 are some of the best I've ever seen.
| WalterBright wrote:
| We list all the changes:
|
| https://dlang.org/changelog/2.095.0.html
| mottosso wrote:
| Yes, this!
| rpearl wrote:
| when we build a new feature, it's gated by a flag controlled by
| the server. The app version with the feature is distributed well
| in advance of the intended rollout. So, we can't even put the new
| feature in the change log for the update that includes the
| feature, and the rollout won't be associated with an app update.
|
| All we can really put in the change log is bug fixes, and the
| circumstances that result in a bug can often be obscure and hard
| to describe in user-facing terms, so it gets summarized: "bug
| fixes and performance improvements". And for the play store and
| the app store, we have to put _something_.
| dasil003 wrote:
| Contrarian viewpoint:
|
| I'm very passionate about this idea for open source software,
| especially things like ruby gems or npm packages that I might use
| as a dependency, but for some reason I can't muster the
| indignation to care about this for apps. Maybe it's because I
| care primarily that the app works and the latest version is
| stable. I'm generally not going in and considering upgrades to
| apps strategically, and even if I did I have no ability to see
| the previous changelogs let alone install those versions. If for
| some reason I want to avoid an upgrade now I'm living on borrowed
| time and need to start thinking about a replacement or carefully
| curate my backups so as not to lose access. Sure in a perfect
| world it would be nice to have perfect changelogs, but it's so
| far down the list of things I want out my apps that I place zero
| value on it.
| p0nce wrote:
| The D compiler have had a great changelog since years and it has
| made a difference to popularize what went into an update. Each
| major change comes with examples, and it's great content.
|
| https://dlang.org/changelog/2.095.0.html
| ulisesrmzroche wrote:
| Maybe like a couple bullet points, nothing too technical, but
| it's a good spot to talk to your customers and make them happy.
|
| It does depend on the product though. I can see a developer tool
| maybe even just going so far as to putting out their internal
| change log, but for other customer segments, it's best to keep it
| short and (hopefully) funny
| rodone wrote:
| Bugfix: closed open single quote in title.
| phreack wrote:
| Worst offenders aren't even those. Some go as far as an
| 'Information not provided by developer', and the worst of them
| all - Netflix's 'You just worry about what to watch next.'.
| Irritates me to no end, I now only update manually and if there's
| no apparent benefit I just don't. Saved me from seeing some apps'
| changing icons into something awful, or hostile UX redesigns. It
| was a shame when Discord, who used to have some of the very best
| changelogs, turned into this practice.
| mottosso wrote:
| This topic and responses to it warms my heart. :) I've made it a
| habit for my current project to turn changelogs into blog-like
| material for the end-user. The kind of changelog I would like to
| see from other software, especially the kind I care about.
|
| For example:
| https://learn.ragdolldynamics.com/releases/2020.12.01/
| brokencode wrote:
| How much value does the average user get out of better patch
| notes? None, since they don't even read the patch notes. So is
| that worth the time for each issue to write and edit a user-
| facing piece of documentation?
|
| Every little task like this is a waste of time and mental energy
| that slows down useful work. In my opinion, this is just not
| worth the effort.
| bartread wrote:
| I too basically disagree with the author (for reasons I'll go
| into below), but I think it's worth unpacking a little further
| that high quality release notes _can_ form an important part of
| your communication strategy with your users. Note: high
| quality.
|
| Many years ago I worked for a tools company where, for our less
| popular tools, user count would be in the thousands to tens of
| thousands, and for the more popular tools, it would be in the
| hundreds of thousands. _Every single time_ we put out a release
| you could guarantee that a handful of people would ask for
| release notes even though we 'd always publish them. Clearly
| people wanted them.
|
| Now I work for a company where our platform caters to two very
| distinct groups of users - one group internal, the other
| external. Particularly for the internal users release notes are
| hugely important in order to avoid disrupting their work and
| deliverables to customers.
|
| In both companies we've often had an "additional bug-fixes and
| performance improvements" item in the list.
|
| Why?
|
| Because people only have so much attention to go around:
| they're busy and, particularly in my current role and with our
| internal users, it's critical that we draw that limited supply
| of attention toward the most important changes. That's much
| more valuable than sending out an exhaustive document of every
| single change every time we do a release. We've found that if
| we supply exhaustive notes, fewer people tend to read them, and
| we get complaints that they're too long. As you've already
| suggested it comes down to ensuring that the release notes you
| provide are actually valuable to users.
|
| Together with other documentation and training materials,
| release notes can provide a useful jumping off point for
| learning how to work with changes and improvements to our
| software.
|
| (Not everybody reads them, of course, but having them does at
| least mean that when they inevitably ask for help/information,
| we can point them at the release notes as a starting point.)
| altitudinous wrote:
| I used to love posting detail about what I change in my apps. But
| now the text isn't really surfaced - folk have automatic updates
| turned on, and the text is deep in the app store now.
|
| My changes are mostly technical when I use the "bug fixes and
| performance improvements" text, but I tend to write more for the
| app store reviewers to let them know what is going on. I know
| they read it.
|
| In the end my audience of users are very non technical. I am
| authentic to them, that is the image that I sell my apps with,
| and I am good at it. So they just don't care that I've updated
| library X, or improved error handling somewhere, or I support
| Apples latest devices now. They do have faith that I am doing the
| right thing, and they write to me as if they know me, and I like
| that.
| Santosh83 wrote:
| These are changelogs for end users, not fellow developers. In
| fact I expect that even these "one line notices" will be
| dispensed with in future as the concept that _any_ software or
| device requires an always-on connection to the Internet becomes
| fully normalised. Apps /devices will simply update and that's
| that. You won't be given any sort of option or toggle. Does
| anyone seriously ask the govt NOT to maintain a road or bridge?
| Such will be the case with software too.
|
| Individual freedoms and privacy have no future in the direction
| technology and society are going.
| blargmaster42_8 wrote:
| Translateing : #$(ticketId) Resolved by $(implementation details)
| into something the end user understands IS HARD!
___________________________________________________________________
(page generated 2021-01-02 23:01 UTC)