4 ms·

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 improvemen

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 8y ago
The most infuriating changelog lines are the ones that just say 'bug fixes' or 'enhancements' (or 'improvements'). Too many change logs have these lines.
- Reedx 8y ago
  True, that doesn't really give much more info than "updated" does.
- ygra 8y ago
  It's a bit annoying to document every single bugfix in a changelog too, though. At least I don't want to read dozens of lines like - Fixed flickering lower-right pixel when hovering over close button with a stylus on devices with more than 300 % UI scaling applied. - Fixed alignment issue in About dialog. - Improved help text for Gizmo frobbing feature. To me a changelog should prominently document changes in function and behaviour. I don't particularly care if an exception message got a typo fixed, but I do care about a new feature, if a login problem for a subset of users has been resolved or a crash under weird circumstances has been fixed.
  - craftyguy 8y ago
    > At least I don't want to read dozens of lines like I must be a crazy user, because I generally like reading through changelogs to see if an update is worth applying because it addresses a specific issue I am having, implements a new interesting feature I want to try, or fixes critical flaws. Luckily, though, public bug trackers are generally a good way to find out at least the 'is my bug fixed' part without the changelog (your issue is closed as 'fixed in X.Y')
  - stared 8y ago
    Yes, it is possible to mention such. It is not important for most users, but super important to ones affected by a given bug. Vide: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0
- bmalehorn 8y ago
  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 8y ago
    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.
  - engerland 8y ago
    We already have our bug tracker for the engineers so why do twice the work? Most engineers don't care once the product is 'out' they only care what they're working on. So we create our change log (they are part of our 'release notes' actually) with only the user in mind but we reference the bug tracker number next to it. This is what we check in to the 'source' for the release notes. Then when we post to the 'outside world' we just remove those tracker numbers (takes a few seconds). That way the engineer can see the 'easy to understand conceptually' bug fix/enhancement and if they want to know more then they can see the Tracker reference and go and look up the 'real meat - with all the discussion and threads etc. For those bug fixes that we 'don't' document we have our source code software.
  - jaxn 8y ago
    We have 4 sections to every changlog release: New, Improved, Fixed, and Internal We maintain a CURRENT_CHANGES.md with those sections. When we do a release, we move the contents of CURRENT_CHANGES to a new entry in RELEASE_NOTES.md. One of these days, I will get around to writing something that displays RELEASE_NOTES in the app, without the Internal section

craftyguy 8y ago

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

Reedx 8y ago
True, that doesn't really give much more info than "updated" does.
ygra 8y ago
It's a bit annoying to document every single bugfix in a changelog too, though. At least I don't want to read dozens of lines like - Fixed flickering lower-right pixel when hovering over close button with a stylus on devices with more than 300 % UI scaling applied. - Fixed alignment issue in About dialog. - Improved help text for Gizmo frobbing feature. To me a changelog should prominently document changes in function and behaviour. I don't particularly care if an exception message got a typo fixed, but I do care about a new feature, if a login problem for a subset of users has been resolved or a crash under weird circumstances has been fixed.
- craftyguy 8y ago
  > At least I don't want to read dozens of lines like I must be a crazy user, because I generally like reading through changelogs to see if an update is worth applying because it addresses a specific issue I am having, implements a new interesting feature I want to try, or fixes critical flaws. Luckily, though, public bug trackers are generally a good way to find out at least the 'is my bug fixed' part without the changelog (your issue is closed as 'fixed in X.Y')
- stared 8y ago
  Yes, it is possible to mention such. It is not important for most users, but super important to ones affected by a given bug. Vide: http://us.battle.net/sc2/en/game/patch-notes/3-9-0 http://us.battle.net/sc2/en/game/patch-notes/3-9-0
bmalehorn 8y ago
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 8y ago
  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.
- engerland 8y ago
  We already have our bug tracker for the engineers so why do twice the work? Most engineers don't care once the product is 'out' they only care what they're working on. So we create our change log (they are part of our 'release notes' actually) with only the user in mind but we reference the bug tracker number next to it. This is what we check in to the 'source' for the release notes. Then when we post to the 'outside world' we just remove those tracker numbers (takes a few seconds). That way the engineer can see the 'easy to understand conceptually' bug fix/enhancement and if they want to know more then they can see the Tracker reference and go and look up the 'real meat - with all the discussion and threads etc. For those bug fixes that we 'don't' document we have our source code software.
- jaxn 8y ago
  We have 4 sections to every changlog release: New, Improved, Fixed, and Internal We maintain a CURRENT_CHANGES.md with those sections. When we do a release, we move the contents of CURRENT_CHANGES to a new entry in RELEASE_NOTES.md. One of these days, I will get around to writing something that displays RELEASE_NOTES in the app, without the Internal section