[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.

[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]

Somebody please tag this issue to disable the 120-day timer to mark Stale since @disassembler's #6051 (comment) indicates that activity on the issue is pending.

[rdlrt]

Somebody please tag this issue to disable the 120-day timer to mark Stale since @disassembler's #6051 (comment) indicates that activity on the issue is pending.

it was my suggestion to include a bot as it gave us very minimalistic control on keeping issue open.
Last year, there was a sweep of all tickets (even tho there were actions against themselves) marking as lacking activity, with a comment to reopen if still needed- while fully knowing that we wont have control to.
The sweep of multiple hundred tickets last year lost a lot of context/feature requests/etc. Atleast with the bot, we just type a . comment and issue will remain open.

Ideally an agreement that no one can run such sweeps would be ideal, but I can imagine everyone has their focus and KPIs to work with, the next best thing I could find was bot

[rphair]

I'm no good with GitHub CI — so I don't see straightaway how to determine whether this is happening — but wouldn't / shouldn't removing the needs triage tag and/or applying some more assertive tag stop that bot from auto-tagging issues as Stale?