[prdoc] Update docs (#3998)

Updating the prdoc doc file to be a bit more useful for new contributors
and adding a SemVer section.

---------

Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>

docs/contributor/prdoc.md

@@ -1,55 +1,31 @@
 # PRDoc
 
-## Intro
-
-With the merge of [PR #1946](https://github.com/paritytech/polkadot-sdk/pull/1946), a new method for
-documenting changes has been introduced: `prdoc`. The [prdoc repository](https://github.com/paritytech/prdoc)
-contains more documentation and tooling.
-
-The current document describes how to quickly get started authoring `PRDoc` files.
+A [prdoc](https://github.com/paritytech/prdoc) is like a changelog but for a Pull Request. We use this approach to
+record changes on a crate level. This information is then processed by the release team to apply the correct crate
+version bumps and to generate the CHANGELOG of the next release.
 
 ## Requirements
 
-When creating a PR, the author needs to decides with the `R0` label whether the change (PR) should
-appear in the release notes or not.
+When creating a PR, the author needs to decide with the `R0-silent` label whether the PR has to contain a prdoc. The
+`R0` label should only be placed for No-OP changes like correcting a typo in a comment or CI stuff. If unsure, ping
+the [CODEOWNERS](../../.github/CODEOWNERS) for advice.
 
-Labelling a PR with `R0` means that no `PRDoc` is required.
+## PRDoc How-To
 
-A PR without the `R0` label **does** require a valid `PRDoc` file to be introduced in the PR.
+A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema). Please follow these steps to generate one:
 
-## PRDoc how-to
+1. Install the [`prdoc` CLI](https://github.com/paritytech/prdoc) by running `cargo install prdoc`.
+1. Open a Pull Request and get the PR number.
+1. Generate the file with `prdoc generate <PR_NUMBER>`. The output filename will be printed.
+1. Optional: Install the `prdoc/schema_user.json` schema in your editor, for example
+[VsCode](https://github.com/paritytech/prdoc?tab=readme-ov-file#schemas).
+1. Edit your `.prdoc` file according to the [Audience](#pick-an-audience) and [SemVer](#record-semver-changes) sections.
+1. Check your prdoc with `prdoc check -n <PR_NUMBER>`. This is optional since the CI will also check it.
 
-A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema).
+> **Tip:** GitHub CLI and jq can be used to provide the number of your PR to generate the correct file:  
+> `prdoc generate $(gh pr view --json number | jq '.number') -o prdoc`
 
-For significant changes, a `.prdoc` file is mandatory and the file must meet the following
-requirements:
-- file named `pr_NNNN.prdoc` where `NNNN` is the PR number.
-  For convenience, those file can also contain a short description: `pr_NNNN_foobar.prdoc`.
-- located under the [`prdoc` folder](https://github.com/paritytech/polkadot-sdk/tree/master/prdoc) of the repository
-- compliant with the [JSON schema](https://json-schema.org/) defined in `prdoc/schema_user.json`
-
-Those requirements can be fulfilled manually without any tooling but a text editor.
-
-## Tooling
-
-Users might find the following helpers convenient:
-- Setup VSCode to be aware of the prdoc schema: see [using VSCode](https://github.com/paritytech/prdoc#using-vscode)
-- Using the `prdoc` cli to:
-  - generate a `PRDoc` file from a [template defined in the Polkadot SDK
-    repo](https://github.com/paritytech/polkadot-sdk/blob/master/prdoc/.template.prdoc) simply providing a PR number
-  - check the validity of one or more `PRDoc` files
-
-## `prdoc` cli usage
-
-The `prdoc` cli documentation can be found at https://github.com/paritytech/prdoc#prdoc
-
-tldr:
-- `prdoc generate <NNNN>`
-- `prdoc check -n <NNNN>`
-
-where <NNNN> is the PR number.
-
-## Pick an audience
+## Pick An Audience
 
 While describing a PR, the author needs to consider which audience(s) need to be addressed.
 The list of valid audiences is described and documented in the JSON schema as follow:
@@ -65,7 +41,41 @@ The list of valid audiences is described and documented in the JSON schema as fo
 
 - `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
 
-## Tips
+If you have a change that affects multiple audiences, you can either list them all, or write multiple sections and
+re-phrase the changes for each audience.
 
-The PRDoc schema is defined in each repo and usually is quite restrictive.
-You cannot simply add a new property to a `PRDoc` file unless the Schema allows it.
+## Record SemVer Changes
+
+All published crates that got modified need to have an entry in the `crates` section of your `PRDoc`. This entry tells
+the release team how to bump the crate version prior to the next release. It is very important that this information is
+correct, otherwise it could break the code of downstream teams.
+
+The bump can either be `major`, `minor`, `patch` or `none`. The three first options are defined by
+[rust-lang.org](https://doc.rust-lang.org/cargo/reference/semver.html), whereas `None` should be picked if no other
+applies. The `None` option is equivalent to the `R0-silent` label, but on a crate level. Experimental and private APIs
+are exempt from bumping and can be broken at any time. Please read the [Crate Section](../RELEASE.md) of the RELEASE doc
+about them.
+
+> **Note**: There is currently no CI in place to sanity check this information, but should be added soon.
+
+### Example
+
+For example when you modified two crates and record the changes:
+
+```yaml
+crates:
+- name: frame-example
+  bump: major
+- name: frame-example-pallet
+  bump: minor
+```
+
+It means that downstream code using `frame-example-pallet` is still guaranteed to work as before, while code using
+`frame-example` might break.
+
+### Dependencies
+
+A crate that depends on another crate will automatically inherit its `major` bumps. This means that you do not need to
+bump a crate that had a SemVer breaking change only from re-exporting another crate with a breaking change.  
+`minor` an `patch` bumps do not need to be inherited, since `cargo` will automatically update them to the latest
+compatible version.

prdoc/schema_user.json

@@ -200,6 +200,11 @@
             "const": "patch",
             "title": "Patch",
             "description": "A bump to the third leftmost non-zero digit of the version number."
+          },
+          {
+            "const": "none",
+            "title": "None",
+            "description": "This change requires no SemVer bump (e.g. change was a test)."
           }
         ]
       },