Consider re-ordering the release notes for point releases

[candlerb]

At https://docs.netbox.dev/en/stable/release-notes/version-3.4/ it shows the release notes newest first, i.e. 3.4.8, then 3.4.7, etc.

However, the most important thing you need when upgrading from previous releases is the "Breaking News" for 3.4.0. This is buried: it's near the end but not actually at the end (because it's followed by other minor features and bug fixes in 3.4.0)

I propose simply reversing the order: so 3.4.0 is top, followed by 3.4.1, 3.4.2 etc. If you want the point release notes then you can scroll to the bottom; or you can just look at them on Github when downloading a specific release.

What do people think?

[jeremystretch]

I don't see how this would improve anything. People either read the change notes or they don't: Reorganizing them wouldn't change this. And I see no reason to deviate from reverse chronological order, which is by far the most common convention. (I don't recall ever seeing it done differently.)

[candlerb]

I can show you an example: Hashicorp Vault. Scroll down to Release notes on the left, select a version like 1.10.0, and you get the release notes for 1.10.0, with all the things you need to know - new features and breaking changes. Point releases aren't included in the manual, since they're always just bugfixes.

Netbox's equivalent is here. The summary page gives a very nice overview of new features, but none of the "Breaking Changes" that you need to know before upgrading to each version. However, if you click on the heading for any particular major version (say 3.4), what you actually get is the release notes for 3.4.8, so you have to wade through pages of content to find the important stuff.

What I'd like to see - either first, or only - on clicking "3.4", is the release notes for 3.4.0. I think it's understood that later 3.4.x releases will be primarily bugfixes, and they shouldn't include breaking changes. If needed, I can get the release notes for point releases on the individual download pages in github.

[mtinberg]

I would say that https://docs.netbox.dev/en/stable/release-notes/version-3.4/#v340-2022-12-14 or really https://github.com/netbox-community/netbox/releases/tag/v3.4.0 is the equivalent of say https://developer.hashicorp.com/vault/docs/release-notes/1.12.0 but you are right in that the most important, must-read notes are the comprehensive major version release notes, so if there was a way to link to those first, or sort them to the top, or make the x.0 notes the contents of the Release Notes Summary page rather than the short list of tickets, that would put the most important information right in front for people reading the docs. I don't know how much that usability improvement would reduce questions or encourage people to read though and where fiddling with the document generation fits into the priority list, the most important thing is continuing to have well written, comprehensive notes but I would guess there is a bigger gap between people who don't read the notes at all and eventually miss critical upgrade steps and cause unnecessary outages for themselves, and those who do read the notes and navigate to the major version x.0 docs than those who hit the summary page and don't navigate further and miss the details. — Mark Tinberg ***@***.***> Division of Information Technology-Network Services University of Wisconsin-Madison

…

________________________________ From: Brian Candler ***@***.***> Sent: Tuesday, April 25, 2023 8:25 AM To: netbox-community/netbox ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [netbox-community/netbox] Consider re-ordering the release notes for point releases (Discussion #12334) I can show you an example: Hashicorp Vault<https://developer.hashicorp.com/vault/docs>. Scroll down to Release notes on the left, select a version like 1.10.0, and you get the release notes for 1.10.0, with all the things you need to know - new features and breaking changes. Point releases aren't included in the manual, since they're always just bugfixes. Netbox's equivalent is here<https://docs.netbox.dev/en/stable/release-notes/>. The summary page gives a very nice overview of new features, but none of the "Breaking Changes" that you need to know before upgrading to each version. However, if you click on the heading for any particular major version (say 3.4), what you actually get is the release notes for 3.4.8, so you have to wade through pages of content to find the important stuff. What I'd like to see - either first, or only - is the release notes for 3.4.0. I think it's understood that later 3.4.x releases will be primarily bugfixes, and they shouldn't include breaking changes. If needed, I can get the release notes for point releases on the individual download pages in github. — Reply to this email directly, view it on GitHub<#12334 (reply in thread)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAS7UMZNBERCRRNNCQ3SYMDXC7GD7ANCNFSM6AAAAAAXJZLYTU>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>