Skip to content
Snippets Groups Projects
Select Git revision
0 results
Blame History Permalink
  • Oliver Tale-Yazdi's avatar
    [CI] Skip SemVer on R0-silent and update docs (#6285) · 9d760a9f
    Oliver Tale-Yazdi authored 
    
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: default avatarOliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
    Unverified
    9d760a9f
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
prdoc.md 5.23 KiB

PRDoc

A 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 for advice.

Auto Generation

You can create a PrDoc by using the /cmd prdoc command (see args with /cmd prdoc --help) in a comment on your PR.

Options:

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

Example

/cmd prdoc --audience runtime_dev --bump patch

Local 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 by running cargo install parity-prdoc.
  2. Open a Pull Request and get the PR number.
  3. Generate the file with prdoc generate <PR_NUMBER>. The output filename will be printed.
  4. Optional: Install the prdoc/schema_user.json schema in your editor, for example VsCode.
  5. Edit your .prdoc file according to the Audience and SemVer sections.
  6. 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

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, 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 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: