diff --git a/.github/scripts/generate-prdoc.py b/.github/scripts/generate-prdoc.py index 780fa0012976..9154f185e64b 100644 --- a/.github/scripts/generate-prdoc.py +++ b/.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 diff --git a/.github/workflows/check-semver.yml b/.github/workflows/check-semver.yml index 16028c8de770..0da3e54ef60b 100644 --- a/.github/workflows/check-semver.yml +++ b/.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 parity-publish@0.10.3 --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" diff --git a/.github/workflows/command-prdoc.yml b/.github/workflows/command-prdoc.yml index 7022e8e0e006..71dbcfbd2289 100644 --- a/.github/workflows/command-prdoc.yml +++ b/.github/workflows/command-prdoc.yml @@ -14,7 +14,7 @@ on: required: true options: - "TODO" - - "no_change" + - "none" - "patch" - "minor" - "major" diff --git a/docs/contributor/prdoc.md b/docs/contributor/prdoc.md index 4a1a3c1f0688..1f6252425e69 100644 --- a/docs/contributor/prdoc.md +++ b/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 `. 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 `. 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 `. 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 `. 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.