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

Ask HN: How do you handle release notes for multiple audiences?

news.ycombinator.com

Post reply on HN
Print view View original

21–30 of 52 posts

Re: Ask HN: How do you handle release notes for multiple audiences?

#21

Post by nofunsir »

bhaney wrote: post #7

As per industry standards: v1.4.18 - "Bug fixes and performance improvements" v1.4.17 - "Bug fixes and performance improvements" v1.4.16 - "Bug fixes and performance improvements"

This should be illegal if auto-updates are enabled or eventual updates are forced. Not joking.

Nowhere else in society do we allow such self-serving laziness and unethical negligence (looking at you, purposely destroying backwards compatibility of APIs) at a professional level. Most other professions have steep legal consequences if they hide their actions or inactions.

Re: Ask HN: How do you handle release notes for multiple audiences?

#22

Post by joshgachnang »

3rodents wrote: post #20
bhaney wrote: post #7

As per industry standards: v1.4.18 - "Bug fixes and performance improvements" v1.4.17 - "Bug fixes and performance improvements" v1.4.16 - "Bug fixes and performance improvements"

Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?

They're required for every version release and no one reads them anyway.

Re: Ask HN: How do you handle release notes for multiple audiences?

#23

Post by hxtk »

The change log for developers/administrators/etc. comes from the Git history. We use conventional commits. Breaking changes in the semantic version of a subcomponent means, "If you're operating this service, you can't just bump the container version and keep your current config.

The change log for end users comes from the JIRA board for the release, looking at what tickets got closed that release cycle, and it usually requires some amount of human effort to rewrite.

Re: Ask HN: How do you handle release notes for multiple audiences?

#25

Post by nofunsir »

3rodents wrote: post #20
bhaney wrote: post #7

As per industry standards: v1.4.18 - "Bug fixes and performance improvements" v1.4.17 - "Bug fixes and performance improvements" v1.4.16 - "Bug fixes and performance improvements"

Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?

Don't underestimate the effort a software developer will put forth to create mountains of complicated automation and scripts if it allows them to be lazy. And they see no issue with this. So why would they see an issue being accountable for yet another agile cycle.

Rev number go up!

Re: Ask HN: How do you handle release notes for multiple audiences?

#26

Post by nofunsir »

joshgachnang wrote: post #22
3rodents wrote: post #20

Earlier quoted context omitted.

Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?

They're required for every version release and no one reads them anyway.

I read every single one. Any app that does this gets uninstalled and a nasty letter to software managers.

Re: Ask HN: How do you handle release notes for multiple audiences?

#27

Post by madaxe_again »

I’ve always gone for a document that expands fractally - that is to say, the title is clear, the opening paragraph gives an overview that a stakeholder would want, the following paragraphs give top level detail for a quick skim/end users, and then you delve into the detail of each feature/fix/etc.

The first sentence should inform of any breaking changes or major (e.g. security) fixes. For instance:

We are pleased to announce the release of version 2.2.1, which includes several fixes for major issues, includes one change which will require action on your part, 36 bug fixes, 12 enhancements, and the new combine harvester feature.

And then you drill into the top level. Also, categorise, it helps people find stuff.

Re: Ask HN: How do you handle release notes for multiple audiences?

#28

Post by internet2000 »

3rodents wrote: post #20
bhaney wrote: post #7

As per industry standards: v1.4.18 - "Bug fixes and performance improvements" v1.4.17 - "Bug fixes and performance improvements" v1.4.16 - "Bug fixes and performance improvements"

Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?

The real answer is this: https://www.reddit.com/r/iOSProgramming/comments/1efubql/im_...

Not only nobody reads them, but Apple forces you to translate them into languages even less than nobody read. It'd be an improvement if they only required English text.

Re: Ask HN: How do you handle release notes for multiple audiences?

#29

Post by kotaKat »

internet2000 wrote: post #28
3rodents wrote: post #20

Earlier quoted context omitted.

Perhaps the perfect time to ask: why are release notes like this on the App Store? Are they a required field and this is the default? Does a popular tool use this value?

The real answer is this: https://www.reddit.com/r/iOSProgramming/comments/1efubql/im_... Not only nobody reads them, but Apple forces you to translate them into languages even less than nobody read. It'd be an improvement if they only required English text.

Meanwhile I see the most bizarre changelogs that I don't understand why Apple approves.

https://apps.apple.com/us/app/chime-mobile-banking/id8362152...

"Choose your own update notes adventure! Pick only one: A, B, or C.

A. The holidays are coming up and we've been busy planning a celebration of bug bashes and performance enhancements, so get merry and smash that update button.

B. Shorter days, longer nights, colder temps. You know what helps the Winter blues?

Instant gratification. Tap update, watch that progress bar fill up, and feel the dopamine flow.

C. Whoever made up the mistletoe thing was crazy. You know what's not? Updating your app."

This... also serves no useful purpose.

Re: Ask HN: How do you handle release notes for multiple audiences?

#30

Post by sevensor »

pletsch wrote: post #9

I think a lot of it boils down to your goals with it, I'm personally very engaged with my user base and take pride in my communication and you may not value that over less work/more dev time. This is also for an internal tool but the audience is diverse (500+ devs, cybersecurity engineers, leadership, writers, etc), I stick with one set of release notes for a few reasons: - One location, people who may fall into mult…

I’m in a similar place with an internal tool. I have a two part changelog. In the first part, each release gets 50 words or less justifying its existence. This is ready to be copy pasted for management consumption. The second part goes into detail about what’s in the release, for technical people who care about those details.
Post reply on HN