[FR] - Node Release Notes Suggestions

[Ranchhand87]

Original Source: https://docs.google.com/document/d/1Sf8HJNfdu-8equF991_NOaZE1vcJiN0fs6cy0z5G_Mg/edit?usp=sharing

Example mithril release notes: https://github.com/input-output-hk/mithril/releases/tag/2450.0

Cardano Node Release Notes Suggestions

Having the repos done in a manner in which we assume this is the first time a user has visited the repo will help document and provide all the needed info. As a small pool and an admin of the xSPO Alliance, an alliance for small pools under a million ada delegated when they join or for brand new pools, we receive a lot of questions that would be eliminated by better documentation on the repo. We see errors from using the wrong version on the network, to not updating config files correctly.

I believe the Mithril team and repo is the gold standard of how the repos should be done.

• Suggestion 1
  Clear callout on what network node version is recommended to be used on.

Have a callout like Mithril does in release notes would great help so people don’t make a mistake

Also have a network Compatibility Chart right in repo

• Suggestion 2
  Include in release notes if there is a configuration file change needed.

Also like Mithril does, they let us know if a configuration update is needed adding to repo would help as well.

• Suggestion 3
  Have the versions listed right in repo

[disassembler]

My comments:

Suggestion 1: Agreed! We'll try to change the template to have this some time in Q1 next year
Suggestion 2: Would you like something like NEW after the link to the configuration files if there are any changes? We made the assumption people download configs from the book every release, but if people don't, I could see that being useful
Suggestion 3: Do you not like the collapsed list? Happy to remove all the collapses if they cause more harm than good. As engineers we thought hiding the details would draw people to the important information and users could epand the sections they care about. I'm open to getting rid of the collapses. It definitely makes the markdown uglier adding the details html tags everywhere to collapse things.

[TerminadaPool]

I like the collapsed lists.

[btbf]

I agree with all the suggestions, but a collapsed format would also be acceptable.

Additionally, it would be helpful if the presence or absence of DB replays is indicated for each lower version.

For example, in the case of 10.1.3:
9.2.1 or below : Required
10.1.1 or above: Not required

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 120 days.

[rphair]

@disassembler we still need this... unless it's been provided in a way I don't know about (in that case please post here).

I would also add... if the focus is the "first time user"... that the release notes should state explicitly when a ledger replay is required on a node version upgrade. The last time this was so, it wasn't mentioned in the release notes. It's a huge penalty in uptime risked for many stake pools by not doing this, and it's a one-liner to add. It may be "understood" that this requirement can be deduced from the version numbering, but:

1. the new SPOs generally won't know that convention;
2. in that last instance, even the old guard SPOs couldn't agree (or find a solid reference on) whether the major or minor version number is the one that indicates a ledger replay, nor whether that convention is consistently followed.