Post AYfUeCYYiOGbCdOx2e by simon@fedi.simonwillison.net
(DIR) More posts by simon@fedi.simonwillison.net
(DIR) Post #AYf7CScj5Ok7yq9b4y by simon@fedi.simonwillison.net
2023-08-12T17:56:19Z
0 likes, 0 repeats
Maybe a better way to think about release notes is that they should read (and be written) like blog entries - each one is a chance to both update the users on the latest news about the project and promote that project to people who haven't discovered it yet
(DIR) Post #AYf7PiYZ9vpj9yWsiW by miki@dragonscave.space
2023-08-12T17:58:33Z
0 likes, 0 repeats
@simon Related, I think all release notes (and release blog posts) should include a one or two sentence summary of what the project is. Those things sometimes end up posted to social media, HN etc, and the user experience is much nicer if the post makes it immediately obvious whether the tool is something you should be interested in or not.
(DIR) Post #AYf7rXZbaWd5CjHZKK by sayrer@mastodon.social
2023-08-12T18:03:28Z
0 likes, 0 repeats
@simon people get really weird about this stuff. I've moved 3 huge apps to “ship every week” schedules instead of big bang semi-annual releases, and there's always some people that go nuts. My absolute favorite is "version inflation”
(DIR) Post #AYf86zJQjkuxZz5B7Q by codinghorror@infosec.exchange
2023-08-12T18:05:53Z
0 likes, 0 repeats
@simon that is literally exactly how we do it at https://discourse.org can recommend 👍
(DIR) Post #AYf8KvCCq4VqrmLboO by Marcus@k8s.social
2023-08-12T18:07:20Z
0 likes, 0 repeats
@simon Kavita does this (e.g. https://github.com/Kareadita/Kavita/releases/tag/v0.7.7). I’m not really a fan and tend to just skip over it and look for a list of any breaking changes. But I have several dozen apps that I keep updated (with Renovate) so don’t have the time to go through all in detail.
(DIR) Post #AYf8yS0amAZ1vWlRUe by simon@fedi.simonwillison.net
2023-08-12T18:16:10Z
0 likes, 0 repeats
@sayrer oh interesting! I don't think I've seen pushback about any of my projects releasing too often, but that's probably because they either don't have huge audiences or don't ship more than once a month or so
(DIR) Post #AYf9iQfw453T741hc8 by sayrer@mastodon.social
2023-08-12T18:24:08Z
0 likes, 0 repeats
@simonFirefox: on version 114Twitter: used a different numbering system, but here: https://androidapksfree.com/twitter/com-twitter-android/old/VSCO: version 333.0Some people get mad when it says “bug fixes and performance improvements", but it's like... what? do you not want those right away?
(DIR) Post #AYfFRwYGtZtYmHxorg by anthrocypher@hachyderm.io
2023-08-12T19:28:10Z
0 likes, 0 repeats
@simon yes! Signal knows what’s up herehttps://hachyderm.io/@anthrocypher/110164249514912641
(DIR) Post #AYfKKh3oanvsTb52xc by bartek@sfba.social
2023-08-12T20:22:59Z
0 likes, 0 repeats
@simon IMO there should be two separate things:- technical release note document with technical details of changes;- a release blog post taking a deep dive into some new features or such.There's quite a few companies doing that.
(DIR) Post #AYfLL3UPIoJTzbFs92 by ImaBMe@mastodon.world
2023-08-12T20:33:59Z
0 likes, 0 repeats
@simon : Anyone needing someone to create those [brilliant idea] blog posts, hit me up!
(DIR) Post #AYfUeCYYiOGbCdOx2e by simon@fedi.simonwillison.net
2023-08-12T22:19:02Z
0 likes, 0 repeats
@bartek I've been trying that for a while with my annotated release notes series - https://simonwillison.net/series/datasette-release-notes/ - but it's begun to feel like maybe I should put all of that effort into just the release notes themselves rather than splitting it into two.
(DIR) Post #AYfVSBmXrtpHHQmNai by bartek@sfba.social
2023-08-12T22:27:57Z
0 likes, 0 repeats
@simon I like an option to quickly browse through a list of changes, especially when debugging some issues and trying to figure which version introduced it. If I had to read a blog post for each release, that would be a bit annoying. I guess what I'm referring to is more of a changelog, but I've been including a copy of the corresponding part of the changelog in the release notes, expanding info as necessary.
(DIR) Post #AYfVgBLyG6Js0N1Pg8 by dreid@wandering.shop
2023-08-12T22:30:16Z
0 likes, 0 repeats
@simon prettier and typescript both always have really good release notes in this fashion.
(DIR) Post #AYfWyCbmQnhl41Zaa0 by nmaggioni@mastodon.nmaggioni.xyz
2023-08-12T22:44:49Z
0 likes, 0 repeats
@simon That sounds just like what Home Assistant does, including screenshot and categorized dropdowns: https://www.home-assistant.io/blog/2023/08/02/release-20238/
(DIR) Post #AYgPMsnuayXEPFStg8 by uliwitness@chaos.social
2023-08-13T08:54:19Z
0 likes, 0 repeats
@simon For conservative definitions of “promote”. Please don’t turn release notes into vapid "we sell happiness" feeds.I've recently been teaching that to new colleagues, what POV to write release notes from, that it's not for people who see the commit logs, but for the people who just pull on a new version, that sorta thing.
(DIR) Post #AYhnIgSH9ty70RprQ8 by chucker@norden.social
2023-08-13T08:52:43Z
0 likes, 0 repeats
@sayrer @simon 1) it’s not about not wanting those. It’s that it doesn’t really go into any detail. It’s also a lie. The Twitter app adds and removes features, moves UI around, etc. all the time. You have no way to consent to that, because their release notes don’t tell you about it.2) the problem with version inflation is it’s very hard to know whether a new version is significant. Back when major UI changes happened in Firefox 2.0, 3.0, 4.0? Easy to watch for those. Hard with 105.0.
(DIR) Post #AYhnIhpM3a1XGJdo24 by sayrer@mastodon.social
2023-08-13T17:31:52Z
0 likes, 0 repeats
@chucker @simon Well, consumer software isn't really done this way anymore. most things are A/B tested and gradually rolled out. So, the number is pretty meaningless. the numbers are kind of an artifact of paid upgrades and distribution on physical media. I know some people don't like it, but no one is going back to that.
(DIR) Post #AYhnIiZRIEt3ZFCbrc by chucker@norden.social
2023-08-13T17:33:35Z
0 likes, 0 repeats
@sayrer @simon but at that point, release notes are meaningless as well, unless you generate them based on the feature flags enabled for a concrete user.(And while I understand the merits of A/B testing, I never consented to it, and find it kind of gross.)
(DIR) Post #AYhnIjM0NfjdzrvOYy by sayrer@mastodon.social
2023-08-13T17:47:23Z
0 likes, 0 repeats
@chucker @simon Usually the way it goes is that it's in the release notes once it's to 100%.Most of the time, it's not done for scummy reasons. It's just a way to iron out problems across large audiences faster than would otherwise be possible.It sounds like you're expecting a level of control that is unrealistic for popular programs. But at least you can make your own Mastodon client and compile a version of Firefox or Chromium that you like. This is better than it used to be.
(DIR) Post #AYhnIkJCpZ5exTcfq4 by simon@fedi.simonwillison.net
2023-08-14T00:56:42Z
0 likes, 0 repeats
@sayrer @chucker I should clarify: I was talking about release notes for things like programming libraries where you need to detail everything because other developers need to know exactly how it all worksI'm still very green when it comes to user-facing documentation for consumer stuff
(DIR) Post #AYiFDCxuAgIWoVo6aG by Ash_Crow@mastodon.social
2023-08-14T06:10:04Z
0 likes, 0 repeats
@simon I quite like the way #WagtailCMS is doing it: https://docs.wagtail.org/en/latest/releases/5.1.html- main new features have each a dedicated section and it is easier to see them when separate from the rest of updates that follows.- They are also written in an end-user-friendly way, and a selection of them are extracted into a "New with Wagtail" post that users are notified of https://docs.wagtail.org/en/latest/releases/5.1.html- update instructions are provided in dedicated sections depending if they affect all projects or not.
(DIR) Post #AYiGKfivkKSnzIvShk by simon@fedi.simonwillison.net
2023-08-14T06:22:44Z
0 likes, 0 repeats
@Ash_Crow wow, those really are excellent