Skip to content

Commit 756a12d

Browse files
chevdorEgorPopelyaevbkchr
authored
PRDoc new schema (#1946)
## Overview This PR brings in the new version of prdoc v0.0.6 and allows: - local schema - local config - local template It also fixes the existing prdoc files to match the new schema. ## todo - [x] add a brief doc/tldr to help contributors get started - [x] test CI - [x] finalize schema - [x] publish the next `prdoc` cli version (v0.0.7 or above) --------- Co-authored-by: Egor_P <egor@parity.io> Co-authored-by: Bastian Köcher <git@kchr.de>
1 parent 1266de3 commit 756a12d

17 files changed

+376
-100
lines changed

‎.github/review-bot.yml

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
rules:
22
- name: CI files
33
condition:
4-
include:
4+
include:
55
- ^\.gitlab-ci\.yml
66
- ^docker/.*
77
- ^\.github/.*
@@ -19,12 +19,12 @@ rules:
1919
- name: Audit rules
2020
type: basic
2121
condition:
22-
include:
22+
include:
2323
- ^polkadot/runtime\/(kusama|polkadot|common)\/.*
2424
- ^polkadot/primitives/src\/.+\.rs$
2525
- ^substrate/primitives/.*
2626
- ^substrate/frame/.*
27-
exclude:
27+
exclude:
2828
- ^polkadot/runtime\/(kusama|polkadot)\/src\/weights\/.+\.rs$
2929
- ^substrate\/frame\/.+\.md$
3030
minApprovals: 1
@@ -80,7 +80,7 @@ rules:
8080
# if there are any changes in the bridges subtree (in case of backport changes back to bridges repo)
8181
- name: Bridges subtree files
8282
type: basic
83-
condition:
83+
condition:
8484
include:
8585
- ^bridges/.*
8686
minApprovals: 1
@@ -91,7 +91,7 @@ rules:
9191

9292
- name: FRAME coders substrate
9393
condition:
94-
include:
94+
include:
9595
- ^substrate/frame/(?!.*(nfts/.*|uniques/.*|babe/.*|grandpa/.*|beefy|merkle-mountain-range/.*|contracts/.*|election|nomination-pools/.*|staking/.*|aura/.*))
9696
type: "and"
9797
reviewers:
@@ -105,7 +105,7 @@ rules:
105105
# Protection of THIS file
106106
- name: Review Bot
107107
condition:
108-
include:
108+
include:
109109
- review-bot\.yml
110110
type: "and"
111111
reviewers:

‎.github/workflows/check-prdoc.yml

+24-12
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,27 @@ on:
66
merge_group:
77

88
env:
9-
IMAGE: paritytech/prdoc:v0.0.5
9+
IMAGE: docker.io/paritytech/prdoc:v0.0.7
1010
API_BASE: https://api.github.com/repos
1111
REPO: ${{ github.repository }}
1212
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
1313
GITHUB_PR: ${{ github.event.pull_request.number }}
14-
MOUNT: /prdoc
1514
ENGINE: docker
15+
PRDOC_DOC: https://github.com/paritytech/polkadot-sdk/blob/master/docs/prdoc.md
1616

1717
jobs:
1818
check-prdoc:
1919
runs-on: ubuntu-latest
2020
steps:
21+
# we cannot show the version in this step (ie before checking out the repo)
22+
# due to https://github.com/paritytech/prdoc/issues/15
2123
- name: Skip merge queue
2224
if: ${{ contains(github.ref, 'gh-readonly-queue') }}
2325
run: exit 0
2426
- name: Pull image
2527
run: |
2628
echo "Pulling $IMAGE"
27-
docker pull $IMAGE
28-
docker run --rm $IMAGE --version
29+
$ENGINE pull $IMAGE
2930
3031
- name: Check if PRdoc is required
3132
id: get-labels
@@ -36,18 +37,29 @@ jobs:
3637
echo "Labels: ${labels}"
3738
echo "labels=${labels}" >> "$GITHUB_OUTPUT"
3839
39-
- name: No PRdoc required
40+
- name: Checkout repo
41+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
42+
43+
- name: Check PRDoc version
44+
run: |
45+
$ENGINE run --rm -v $PWD:/repo $IMAGE --version
46+
47+
- name: Early exit if PR is silent
4048
if: ${{ contains(steps.get-labels.outputs.labels, 'R0') }}
4149
run: |
42-
echo "PR detected as silent, no PRdoc is required, exiting..."
50+
hits=$(find prdoc -name "pr_$GITHUB_PR*.prdoc" | wc -l)
51+
if (( hits > 0 )); then
52+
echo "PR detected as silent, but a PRDoc was found, checking it as information"
53+
$ENGINE run --rm -v $PWD:/repo $IMAGE check -n ${GITHUB_PR} || echo "Ignoring failure"
54+
else
55+
echo "PR detected as silent, no PRDoc found, exiting..."
56+
fi
57+
echo "If you want to add a PRDoc, please refer to $PRDOC_DOC"
4358
exit 0
4459
45-
- name: Checkout repo
46-
if: ${{ !contains(steps.get-labels.outputs.labels, 'R0') }}
47-
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
48-
4960
- name: PRdoc check for PR#${{ github.event.pull_request.number }}
5061
if: ${{ !contains(steps.get-labels.outputs.labels, 'R0') }}
5162
run: |
52-
echo "Checking for PR#${GITHUB_PR} in $MOUNT"
53-
$ENGINE run --rm -v $PWD/prdoc:/doc $IMAGE check -n ${GITHUB_PR} || true
63+
echo "Checking for PR#${GITHUB_PR}"
64+
echo "You can find more information about PRDoc at $PRDOC_DOC"
65+
$ENGINE run --rm -v $PWD:/repo $IMAGE check -n ${GITHUB_PR}

‎.prdoc.toml

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Config file for prdoc, see https://github.com/paritytech/prdoc
2+
3+
version = 1
4+
schema = "prdoc/schema_user.json"
5+
output_dir = "prdoc"
6+
prdoc_folders = ["prdoc"]
7+
template = "prdoc/.template.prdoc"

‎docs/CONTRIBUTING.md

+2-12
Original file line numberDiff line numberDiff line change
@@ -93,22 +93,12 @@ The reviewers are also responsible to check:
9393

9494
All Pull Requests must contain proper title & description.
9595

96-
Some Pull Requests can be exempt of `prdoc` documentation, those
97-
must be labelled with
96+
Some Pull Requests can be exempt of `prdoc` documentation, those must be labelled with
9897
[`R0-silent`](https://github.com/paritytech/labels/blob/main/ruled_labels/specs_polkadot-sdk.yaml#L89-L91).
9998

10099
Non "silent" PRs must come with documentation in the form of a `.prdoc` file.
101-
A `.prdoc` documentation is made of a text file (YAML) named `/prdoc/pr_NNNN.prdoc` where `NNNN` is the PR number.
102-
For convenience, those file can also contain a short description/title: `/prdoc/pr_NNNN_pr-foobar.prdoc`.
103100

104-
The CI automation checks for the presence and validity of a `prdoc` in the `/prdoc` folder.
105-
Those files need to comply with a specific [schema](https://github.com/paritytech/prdoc/blob/master/schema_user.json). It
106-
is highly recommended to [make your editor aware](https://github.com/paritytech/prdoc#schemas) of the schema as it is
107-
self-described and will assist you in writing correct content.
108-
109-
This schema is also embedded in the
110-
[prdoc](https://github.com/paritytech/prdoc) utility that can also be used to generate and check the validity of a
111-
`prdoc` locally.
101+
See more about `prdoc` [here](./prdoc.md)
112102

113103
## Helping out
114104

‎docs/DOCUMENTATION_GUIDELINES.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ For the top-level pallet docs, consider the following template:
225225
//!
226226
//! ## Pallet API
227227
//!
228-
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat
228+
//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat
229229
//! things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the line below as-is:>
230230
//!
231231
//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its
@@ -349,3 +349,7 @@ Consider the fact that, similar to dispatchables, these docs will be part of the
349349
and might be used by wallets and explorers.
350350

351351
Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it.
352+
353+
## Documenting Changes/PR
354+
355+
See [PRDoc](./prdoc.md).

‎docs/prdoc.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# PRDoc
2+
3+
## Intro
4+
5+
With the merge of [PR #1946](https://github.com/paritytech/polkadot-sdk/pull/1946), a new method for
6+
documenting changes has been introduced: `prdoc`. The [prdoc repository](https://github.com/paritytech/prdoc)
7+
contains more documentation and tooling.
8+
9+
The current document describes how to quickly get started authoring `PRDoc` files.
10+
11+
## Requirements
12+
13+
When creating a PR, the author needs to decides with the `R0` label whether the change (PR) should
14+
appear in the release notes or not.
15+
16+
Labelling a PR with `R0` means that no `PRDoc` is required.
17+
18+
A PR without the `R0` label **does** require a valid `PRDoc` file to be introduced in the PR.
19+
20+
## PRDoc how-to
21+
22+
A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema).
23+
24+
For significant changes, a `.prdoc` file is mandatory and the file must meet the following
25+
requirements:
26+
- file named `pr_NNNN.prdoc` where `NNNN` is the PR number.
27+
For convenience, those file can also contain a short description: `pr_NNNN_foobar.prdoc`.
28+
- located under the [`prdoc` folder](https://github.com/paritytech/polkadot-sdk/tree/master/prdoc) of the repository
29+
- compliant with the [JSON schema](https://json-schema.org/) defined in `prdoc/schema_user.json`
30+
31+
Those requirements can be fulfilled manually without any tooling but a text editor.
32+
33+
## Tooling
34+
35+
Users might find the following helpers convenient:
36+
- Setup VSCode to be aware of the prdoc schema: see [using VSCode](https://github.com/paritytech/prdoc#using-vscode)
37+
- Using the `prdoc` cli to:
38+
- generate a `PRDoc` file from a [template defined in the Polkadot SDK
39+
repo](https://github.com/paritytech/polkadot-sdk/blob/master/prdoc/.template.prdoc) simply providing a PR number
40+
- check the validity of one or more `PRDoc` files
41+
42+
## `prdoc` cli usage
43+
44+
The `prdoc` cli documentation can be found at https://github.com/paritytech/prdoc#prdoc
45+
46+
tldr:
47+
- `prdoc generate <NNNN>`
48+
- `prdoc check -n <NNNN>`
49+
50+
where <NNNN> is the PR number.
51+
52+
## Pick an audience
53+
54+
While describing a PR, the author needs to consider which audience(s) need to be addressed.
55+
The list of valid audiences is described and documented in the JSON schema as follow:
56+
57+
- `Node Dev`: Those who build around the client side code. Alternative client builders, SMOLDOT, those who consume RPCs.
58+
These are people who are oblivious to the runtime changes. They only care about the meta-protocol, not the protocol
59+
itself.
60+
61+
- `Runtime Dev`: All of those who rely on the runtime. A parachain team that is using a pallet. A DApp that is using a
62+
pallet. These are people who care about the protocol (WASM), not the meta-protocol (client).
63+
64+
- `Node Operator`: Those who don't write any code and only run code.
65+
66+
- `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
67+
68+
## Tips
69+
70+
The PRDoc schema is defined in each repo and usually is quite restrictive.
71+
You cannot simply add a new property to a `PRDoc` file unless the Schema allows it.

‎prdoc/.template.prdoc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
2+
# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
3+
4+
title: ...
5+
6+
doc:
7+
- audience: Node Dev
8+
description: |
9+
...
10+
11+
crates: [ ]

‎prdoc/pr_1226.prdoc

+5-10
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
11
title: Removed deprecated `Balances::transfer` and `Balances::set_balance_deprecated` functions.
22

33
doc:
4-
- audience: Builder
5-
description: The Balances pallet's dispatchables `set_balance_deprecated` and `transfer` were deprecated in [paritytech/substrate#12951](https://github.com/paritytech/substrate/pull/12951) and have now been removed.
6-
notes:
7-
- Use `set_balance_deprecated` instead `force_set_balance` and `transfer_allow_death` instead of `transfer`.
8-
9-
migrations:
10-
db: []
4+
- audience: Runtime User
5+
description: |
6+
The Balances pallet's dispatchables `set_balance_deprecated` and `transfer` were deprecated in [paritytech/substrate#12951](https://github.com/paritytech/substrate/pull/12951) and have now been removed.
117

12-
runtime: []
8+
notes:
9+
- Use `set_balance_deprecated` instead `force_set_balance` and `transfer_allow_death` instead of `transfer`.
1310

1411
crates:
1512
- name: pallet-balances
16-
17-
host_functions: []

‎prdoc/pr_1234.prdoc

+2-9
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,10 @@
44
title: Introduce XcmFeesToAccount fee manager
55

66
doc:
7-
- audience: Builder
7+
- audience: Runtime User
88
description: |
99
Now all XCM sending, unless done by the system for the system, will be charged delivery fees.
1010
All runtimes are now configured to send these delivery fees to a treasury account.
1111
The fee formula is `delivery_fee_factor * (base_fee + encoded_msg_len * per_byte_fee)`.
1212

13-
migrations:
14-
db: []
15-
16-
runtime: []
17-
18-
crates: []
19-
20-
host_functions: []
13+
crates: [ ]

‎prdoc/pr_1255.prdoc

+7-8
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,18 @@
44
title: Fix for Reward Deficit in the pool
55

66
doc:
7-
- audience: Core Dev
8-
description: Instead of fragile calculation of current balance by looking at free balance - ED, Nomination Pool now freezes ED in the pool reward account to restrict an account from going below minimum balance. This also has a nice side effect that if ED changes, we know how much is the imbalance in ED frozen in the pool and the current required ED. A pool operator can diligently top up the pool with the deficit in ED or vice versa, withdraw the excess they transferred to the pool.
9-
notes:
7+
- audience: Runtime Dev
8+
description: |
9+
Instead of fragile calculation of current balance by looking at free balance - ED, Nomination Pool now freezes ED in the pool reward account to restrict an account from going below minimum balance. This also has a nice side effect that if ED changes, we know how much is the imbalance in ED frozen in the pool and the current required ED. A pool operator can diligently top up the pool with the deficit in ED or vice versa, withdraw the excess they transferred to the pool.
10+
11+
notes:
1012
- Introduces new call `adjust_pool_deposit` that allows to top up the deficit or withdraw the excess deposit for the pool.
1113
- Switch to using Fungible trait from Currency trait.
1214

1315
migrations:
14-
db: []
15-
1616
runtime:
17-
- { pallet: "pallet-nomination-pools", description: "One time migration of freezing ED from each of the existing pools."}
17+
- reference: pallet-nomination-pools
18+
description: One time migration of freezing ED from each of the existing pools.
1819

1920
crates:
2021
- name: pallet-nomination-pools
21-
22-
host_functions: []

‎prdoc/pr_1408_prodc-introduction.prdoc

+2-9
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,11 @@
22
title: PRdoc check
33

44
doc:
5-
- audience: Core Dev
5+
- audience: Node Dev
66
description: |
77
This PRdoc is an **example**.
88

99
This PR brings support and automated checks for documentation in the form of a
1010
[`prdoc`](https://github.com/paritytech/prdoc/) file.
1111

12-
migrations:
13-
db: []
14-
15-
runtime: []
16-
17-
crates: []
18-
19-
host_functions: []
12+
crates: [ ]

‎prdoc/pr_1818.prdoc

+2-9
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,9 @@
11
title: FRAME pallets warning for unchecked weight witness
22

33
doc:
4-
- audience: Core Dev
4+
- audience: Runtime Dev
55
description: |
66
FRAME pallets now emit a warning when a call uses a function argument that starts with an underscore in its weight declaration.
77

8-
migrations:
9-
db: [ ]
10-
runtime: [ ]
11-
12-
host_functions: []
13-
148
crates:
15-
- name: "frame-support-procedural"
16-
semver: minor
9+
- name: frame-support-procedural

‎prdoc/pr_1873.prdoc

+3-9
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,9 @@
11
title: Message Queue use proper overweight limit
22

33
doc:
4-
- audience: Core Dev
4+
- audience: Node Dev
55
description: |
66
Changed the overweight cutoff limit from the full `Config::ServiceWeight` to a lower value that is calculated based on the weight of the functions being called.
77

8-
migrations:
9-
db: []
10-
11-
runtime: []
12-
13-
crates: ["pallet-message-queue", patch]
14-
15-
host_functions: []
8+
crates:
9+
- name: pallet-message-queue

‎prdoc/pr_1913.prdoc

-7
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,6 @@ doc:
77
If experiencing stability issues caused by BEEFY, it can be disabled using `--no-beefy` flag.
88
BEEFY doesn't (yet) support warp sync. So, attempting to Warp sync as a validator will throw an error.
99

10-
migrations:
11-
db: []
12-
13-
runtime: []
14-
1510
crates:
1611
- name: polkadot-cli
1712
- name: polkadot-service
18-
19-
host_functions: []

0 commit comments

Comments
 (0)