[Content] Upgrade Instructions guidelines

[gnunicorn]

Content request

Substrate and Polkadot want to do better on releasing. A key aspect we've identified as problematic for people using our code is that it is hard to figure out what broke and what they should be doing about it – our current changelog list the breaking PRs but there is little to no information helping people fix their problem. We want to change that and enforce a CI-job that requires people to provide proper upgrade instructions on PRs marked as breaking. But "what are proper upgrade instructions".

It would be amazing if the docs team could provide a concise document outlining how to write good upgrade instructions, what should included (examples? diffs?), what should be left out as a helper and reference for devs and reviewers when writing and reviewing these instructions. Please also include a brief mention of grammar or other language aspects we usually enforce to stay consistent with the other docs (or a link to it).

Are you willing to help with this request?

Maybe (please specify)

[nuke-web3]

One approach could be:

1. Clone upstream at your version of a template (as this is likely what you used to start, and has the lowest churn from version to version)
2. In a new branch based on this, do a squash merge with the target release
3. Inspect the diff and/or create patch files
4. Apply differences by hand or patch
5. (if needed) copy the upstream Cargo.lock for the target release to move to, and let cargo use the locks exactly as it does (the highest level dependency tree one, in order: {your custom/community deps} Cumulus, Polkadot, Substrate)
6. 🙏 The Substrate and rust gods smile down on your build
   Anything I would be missing other than details and examples for this?

[lsgunnlsgunn]

Upgrade instructions should include a brief description of what changed, why it changed, and any specific steps someone should follow to use the upgraded crate in practice. Do I need to modify a Cargo.toml file? Do I need to recompile the node-template, the front-end template, substrate itself?
I like Dan's practical approach, maybe we could add a list of the kinds of things that people have had to do in the past to fix the environment after a breaking change. Is that feasible to add?