mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-26 09:57:56 +00:00
Oliver Tale-Yazdi
753bf2d860
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>
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
|
|
## PRDoc How-To
|
|
|
|
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 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`
|
|
|
|
## 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:
|
|
|
|
- `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.
|
|
|
|
- `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).
|
|
|
|
- `Node Operator`: Those who don't write any code and only run code.
|
|
|
|
- `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
|
|
|
|
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.
|
|
|
|
## 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.
|