mirror of
https://github.com/pezkuwichain/docs.git
synced 2026-04-22 05:27:55 +00:00
docs: add Pezkuwi-SDK documentation
- Technical documentation - SDK guides - Architecture overview - Whitepaper - Contributor guides
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
# 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-no-crate-publish-required` 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.
|
||||
|
||||
## 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 teyrchain 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
|
||||
|
||||
```bash
|
||||
/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](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`
|
||||
|
||||
## 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-no-crate-publish-required` 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Overwrite CI Check
|
||||
|
||||
The `check-semver` CI check is doing sanity checks based on the provided `PRDoc` and the mentioned
|
||||
crate version bumps. The tooling is not perfect and it may recommends incorrect bumps of the version.
|
||||
The CI check can be forced to accept the provided version bump. This can be done like:
|
||||
|
||||
```yaml
|
||||
crates:
|
||||
- name: frame-example
|
||||
bump: major
|
||||
validate: false
|
||||
- name: frame-example-pallet
|
||||
bump: minor
|
||||
```
|
||||
|
||||
By putting `validate: false` for `frame-example`, the version bump is ignored by the tooling. For
|
||||
`frame-example-pallet` the version bump is still validated by the CI check.
|
||||
|
||||
### Backporting PRs
|
||||
|
||||
When [backporting changes](../BACKPORT.md) to a stable release branch (e.g. `stable2503`), stricter versioning rules
|
||||
apply to minimise risk for downstream users.
|
||||
|
||||
#### ✅ Allowed Bump Levels
|
||||
|
||||
Only the following `bump` levels are allowed by default:
|
||||
|
||||
- `none`: No observable change. No detectable difference between old and new versions.
|
||||
- `patch`: Bug fixes or internal changes. Do not affect functionality or cause compilation errors.
|
||||
- `minor`: Backward-compatible additions. Safe to adopt; adds features only, no behaviour changes.
|
||||
|
||||
Backport PRs with `major` bumps will fail CI.
|
||||
|
||||
#### 🚨 Overriding the CI Check
|
||||
|
||||
If a `major` bump is truly needed, you must:
|
||||
|
||||
1. Set `validate: false` in the `.prdoc`. See [Overwrite CI Check](#overwrite-ci-check).
|
||||
2. Include a justification in the PR description explaining:
|
||||
- Why the bump is necessary.
|
||||
- Why it is safe for downstream users.
|
||||
3. Notify a release engineer or senior reviewer for approval.
|
||||
|
||||
> Use this override sparingly, and only when you’re confident the change is safe and justified.
|
||||
Reference in New Issue
Block a user