[CI] Skip SemVer on R0-silent and update docs

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