[CI] Skip SemVer on R0-silent and update docs (#6285)

Changes:
- Make R0-silent not run the semver check again. Originally I thought
this would be good to have a bullet-proof check, but it now often
triggers when CI or unrelated files are changed. In the end, the
developer has to make the right choice here - and always will need to.
So bringing back the R0 label gives more power to the devs and should
increase dev velocity. We still need to ensure that every use of this
label is well understood, and not just used out of lazyness.
- Fix `/cmd prdoc` bump levels
- Update docs

---------

Signed-off-by: Oliver Tale-Yazdi <[email protected]>

.github/scripts/generate-prdoc.py

@@ -36,6 +36,21 @@ def from_pr_number(n, audience, bump, force):
 
 	create_prdoc(n, audience, pr.title, pr.body, patch, bump, force)
 
+def translate_audience(audience):
+	aliases = {
+		'runtime_dev': 'Runtime Dev',
+		'runtime_user': 'Runtime Operator',
+		'node_dev': 'Node Dev',
+		'node_user': 'Node User',
+	}
+
+	if audience in aliases:
+		to = aliases[audience]
+		print(f"Translated audience '{audience}' to '{to}'")
+		audience = to
+
+	return audience
+
 def create_prdoc(pr, audience, title, description, patch, bump, force):
 	path = f"prdoc/pr_{pr}.prdoc"
 
@@ -49,6 +64,7 @@ def create_prdoc(pr, audience, title, description, patch, bump, force):
 		print(f"No preexisting PrDoc for PR {pr}")
 
 	prdoc = { "title": title, "doc": [{}], "crates": [] }
+	audience = translate_audience(audience)
 
 	prdoc["doc"][0]["audience"] = audience
 	prdoc["doc"][0]["description"] = description
@@ -117,7 +133,7 @@ def setup_parser(parser=None, pr_required=True):
 		parser = argparse.ArgumentParser()
 	parser.add_argument("--pr", type=int, required=pr_required, help="The PR number to generate the PrDoc for.")
 	parser.add_argument("--audience", type=str, nargs='*', choices=allowed_audiences, default=["todo"], help="The audience of whom the changes may concern. Example: --audience runtime_dev node_dev")
-	parser.add_argument("--bump", type=str, default="major", choices=["patch", "minor", "major", "silent", "ignore", "no_change"], help="A default bump level for all crates. Example: --bump patch")
+	parser.add_argument("--bump", type=str, default="major", choices=["patch", "minor", "major", "silent", "ignore", "none"], help="A default bump level for all crates. Example: --bump patch")
 	parser.add_argument("--force", action="store_true", help="Whether to overwrite any existing PrDoc.")
 	return parser
 

.github/workflows/check-semver.yml

@@ -2,7 +2,7 @@ name: Check semver
 
 on:
   pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
   workflow_dispatch:
   merge_group:
 
@@ -62,21 +62,29 @@ jobs:
 
           echo "PRDOC_EXTRA_ARGS=--max-bump minor" >> $GITHUB_ENV
 
+      - name: Echo Skip
+        if: ${{ contains(github.event.pull_request.labels.*.name, 'R0-silent') }}
+        run: echo "Skipping this PR because it is labeled as R0-silent."
+
       - name: Rust Cache
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'R0-silent') }}
         uses: Swatinem/rust-cache@82a92a6e8fbeee089604da2575dc567ae9ddeaab # v2.7.5
         with:
           cache-on-failure: true
 
       - name: Rust compilation prerequisites
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'R0-silent') }}
         run: |
           rustup default $TOOLCHAIN
           rustup component add rust-src --toolchain $TOOLCHAIN
 
       - name: install parity-publish
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'R0-silent') }}
         # Set the target dir to cache the build.
         run: CARGO_TARGET_DIR=./target/ cargo install [email protected] --locked -q
 
       - name: check semver
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'R0-silent') }}
         run: |
           if [ -z "$PR" ]; then
             echo "Skipping master/merge queue"

.github/workflows/command-prdoc.yml

@@ -14,7 +14,7 @@ on:
         required: true
         options:
           - "TODO"
-          - "no_change"
+          - "none"
           - "patch"
           - "minor"
           - "major"

docs/contributor/prdoc.md

@@ -1,73 +1,88 @@
 # PRDoc
 
-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.
+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 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.
+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.
 
-## PRDoc How-To
+## Auto Generation
 
-A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema). Please follow these steps to generate one:
-
-1. Install the [`prdoc` CLI](https://github.com/paritytech/prdoc) by running `cargo install parity-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.
-
-> **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`
-
-Alternatively you can call the prdoc from PR via `/cmd prdoc` (see args with `/cmd prdoc --help`)
-in a comment to PR to trigger it from CI.
+You can create a PrDoc by using the `/cmd prdoc` command (see args with `/cmd prdoc --help`) in a
+comment on your PR.
 
 Options:
 
-- `pr`: The PR number to generate the PrDoc for.
-- `audience`: The audience of whom the changes may concern.
-- `bump`: A default bump level for all crates.
-  The PrDoc will likely need to be edited to reflect the actual changes after generation.
-- `force`: Whether to overwrite any existing PrDoc.
+- `audience` The audience of whom the changes may concern.
+  - `runtime_dev`: Anyone building a runtime themselves. For example parachain teams, or people
+    providing template runtimes. Also devs using pallets, FRAME etc directly. These are people who
+    care about the protocol (WASM), not the meta-protocol (client).
+  - `runtime_user`: Anyone using the runtime. Can be front-end devs reading the state, exchanges
+    listening for events, libraries that have hard-coded pallet indices etc. Anything that would
+    result in an observable change to the runtime behaviour must be marked with this.
+  - `node_dev`: Those who build around the client side code. Alternative client builders, SMOLDOT,
+  those who consume RPCs. These are people who are oblivious to the runtime changes. They only care
+  about the meta-protocol, not the protocol itself.
+  - `node_operator`: People who run the node. Think of validators, exchanges, indexer services, CI
+    actions. Anything that modifies how the binary behaves (its arguments, default arguments, error
+    messags, etc) must be marked with this.
+- `bump:`: The default bump level for all crates. The PrDoc will likely need to be edited to reflect
+  the actual changes after generation. More details in the section below.
+  - `none`: There is no observable change. So to say: if someone were handed the old and the new
+    version of our software, it would be impossible to figure out what version is which.
+  - `patch`: Fixes that will never cause compilation errors if someone updates to this version. No
+    functionality has been changed. Should be limited to fixing bugs or No-OP implementation
+    changes.
+  - `minor`: Additions that will never cause compilation errors if someone updates to this version.
+    No functionality has been changed. Should be limited to adding new features.
+  - `major`: Anything goes.
+- `force: true|false`: Whether to overwrite any existing PrDoc file.
 
-## 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:
+### Example
 
-- `Node Dev`: Those who build around the client side code. Alternative client builders, SMOLDOT, those who consume RPCs.
-  These are people who are oblivious to the runtime changes. They only care about the meta-protocol, not the protocol
-  itself.
+```bash
+/cmd prdoc --audience runtime_dev --bump patch
+```
 
-- `Runtime Dev`: All of those who rely on the runtime. A parachain team that is using a pallet. A DApp that is using a
-  pallet. These are people who care about the protocol (WASM), not the meta-protocol (client).
+## Local Generation
 
-- `Node Operator`: Those who don't write any code and only run code.
+A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema). Please follow these steps
+to generate one:
 
-- `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
+1. Install the [`prdoc` CLI](https://github.com/paritytech/prdoc) by running `cargo install
+   parity-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.
 
-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.
+> **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`
 
 ## 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.
+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.
+[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.
+> **Note**: There is currently no CI in place to sanity check this information, but should be added
+> soon.
 
 ### Example
 
@@ -81,12 +96,13 @@ crates:
     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.
+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.
+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.