paritytech · chevdor · Dec 4, 2023 · Oct 18, 2023 · Oct 19, 2023 · Oct 19, 2023
@@ -5,23 +5,23 @@ on:
     types: [labeled, opened, synchronize, unlabeled]
 
 env:
-  IMAGE: paritytech/prdoc:v0.0.5
+  IMAGE: docker.io/paritytech/prdoc:v0.0.6
   API_BASE: https://api.github.com/repos
   REPO: ${{ github.repository }}
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   GITHUB_PR: ${{ github.event.pull_request.number }}
-  MOUNT: /prdoc
   ENGINE: docker
 
 jobs:
   check-prdoc:
     runs-on: ubuntu-latest
     steps:
+      # we cannot show the version in this step (ie before checking out the repo)
+      # due to https://github.com/paritytech/prdoc/issues/15
       - name: Pull image
         run: |
           echo "Pulling $IMAGE"
-          docker pull $IMAGE
-          docker run --rm $IMAGE --version
+          $ENGINE pull $IMAGE
 
       - name: Check if PRdoc is required
         id: get-labels
@@ -32,18 +32,27 @@ jobs:
           echo "Labels: ${labels}"
           echo "labels=${labels}" >> "$GITHUB_OUTPUT"
 
-      - name: No PRdoc required
+      - name: Checkout repo
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+
+      - name: Check PRDoc version
+        run: |
+          $ENGINE run --rm -v $PWD:/repo $IMAGE --version
+
+      - name: Early exit if PR is silent
         if: ${{ contains(steps.get-labels.outputs.labels, 'R0') }}
         run: |
-          echo "PR detected as silent, no PRdoc is required, exiting..."
+          hits=$(find prdoc -name "pr_$GITHUB_PR*.prdoc" | wc -l)
+          if (( hits > 0 )); then
+            echo "PR detected as silent, but a PRDoc was found, checking it as information"
+            $ENGINE run --rm -v $PWD:/repo $IMAGE check -n ${GITHUB_PR} || echo "Ignoring failure"
+          else
+            echo "PR detected as silent, no PRDoc found, exiting..."
+          fi
           exit 0
 
-      - name: Checkout repo
-        if: ${{ !contains(steps.get-labels.outputs.labels, 'R0') }}
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
-
       - name: PRdoc check for PR#${{ github.event.pull_request.number }}
         if: ${{ !contains(steps.get-labels.outputs.labels, 'R0') }}
         run: |
-          echo "Checking for PR#${GITHUB_PR} in $MOUNT"
-          $ENGINE run --rm -v $PWD/prdoc:/doc $IMAGE check -n ${GITHUB_PR} || true
+          echo "Checking for PR#${GITHUB_PR}"
+          $ENGINE run --rm -v $PWD:/repo $IMAGE check -n ${GITHUB_PR}
diff --git a/.prdoc.toml b/.prdoc.toml
@@ -0,0 +1,7 @@
+# Config file for prdoc, see https://github.com/paritytech/prdoc
+
+version = 1
+schema = "prdoc/schema_user.json"
+output_dir = "prdoc"
+prdoc_folders = ["prdoc"]
+template = "prdoc/.template.prdoc"
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -93,22 +93,12 @@ The reviewers are also responsible to check:
 
 All Pull Requests must contain proper title & description.
 
-Some Pull Requests can be exempt of `prdoc` documentation, those
-must be labelled with
+Some Pull Requests can be exempt of `prdoc` documentation, those must be labelled with
 [`R0-silent`](https://github.com/paritytech/labels/blob/main/ruled_labels/specs_polkadot-sdk.yaml#L89-L91).
 
 Non "silent" PRs must come with documentation in the form of a `.prdoc` file.
-A `.prdoc` documentation is made of a text file (YAML) named `/prdoc/pr_NNNN.prdoc` where `NNNN` is the PR number.
-For convenience, those file can also contain a short description/title: `/prdoc/pr_NNNN_pr-foobar.prdoc`.
 
-The CI automation checks for the presence and validity of a `prdoc` in the `/prdoc` folder.
-Those files need to comply with a specific [schema](https://github.com/paritytech/prdoc/blob/master/schema_user.json). It
-is highly recommended to [make your editor aware](https://github.com/paritytech/prdoc#schemas) of the schema as it is
-self-described and will assist you in writing correct content.
-
-This schema is also embedded in the
-[prdoc](https://github.com/paritytech/prdoc) utility that can also be used to generate and check the validity of a
-`prdoc` locally.
+See more about `prdoc` [here](./prdoc.md)
 
 ## Helping out
 

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
@@ -225,7 +225,7 @@ For the top-level pallet docs, consider the following template:
 //!
 //! ## Pallet API
 //!
-//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat 
+//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat
 //! things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the line below as-is:>
 //!
 //! 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
 and might be used by wallets and explorers.
 
 Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it.
+
+## Documenting Changes/PR
+
+See [PRDoc](./prdoc.md).
diff --git a/docs/prdoc.md b/docs/prdoc.md
@@ -0,0 +1,50 @@
+# PRDoc
+
+## Intro
+
+With the merge of [PR #1946](https://github.com/paritytech/polkadot-sdk/pull/1946), a new method for
+documenting changes has been introduced: `prdoc`. The [prdoc repository](https://github.com/paritytech/prdoc)
+contains more documentation and tooling.
+
+The current document describes how to quickly get started authoring `PRDoc` files.
+
+## Requirements
+
+When creating a PR, the author needs to decides with the `R0` label whether the change (PR) should
+appear in the release notes or not.
+
+Labelling a PR with `R0` means that no `PRDoc` is required.
+
+A PR without the `R0` label **does** require a valid `PRDoc` file to be introduced in the PR.
+
+## PRDoc how-to
+
+A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema).
+
+For significant changes, a `.prdoc` file is mandatory and the file must meet the following
+requirements:
+- file named `pr_NNNN.prdoc` where `NNNN` is the PR number.
+  For convenience, those file can also contain a short description: `pr_NNNN_foobar.prdoc`.
+- located under the [`prdoc` folder](https://github.com/paritytech/polkadot-sdk/tree/master/prdoc) of the repository
+- compliant with the [JSON schema](https://json-schema.org/) defined in `prdoc/schema_user.json`
+
+Those requirements can be fulfilled manually without any tooling but a text editor.
+
+## Tooling
+
+Users might find the following helpers convenient:
+- Setup VSCode to be aware of the prdoc schema: see [using VSCode](https://github.com/paritytech/prdoc#using-vscode)
+- Using the `prdoc` cli to:
+  - generate a `PRDoc` file from a [template defined in the Polkadot SDK
+    repo](https://github.com/paritytech/polkadot-sdk/blob/master/prdoc/.template.prdoc) simply providing a PR number
+  - check the validity of one or more `PRDoc` files
+
+## Tips
+
+The PRDoc schema is defined in each repo and usually is quite restrictive.
+You cannot simply add a new property to a `PRDoc` file unless the Schema allows it.
+
+There are however a few convenience optional properties that could be useful to authors:
+- `authors`: An array of authors (strings). That can help an author find their PRs easily
+- `tags`: Array of strings. Those are unrelated to the Github Labels and provided for
+  authors to flag their changes as  they wish, in order to find PR and Documentation quicker
diff --git a/prdoc/.template.prdoc b/prdoc/.template.prdoc
@@ -0,0 +1,18 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: ...
+
+doc:
+  - audience: Node Dev
+    description: |
+      ...
+
+migrations:
+  db: []
+
+  runtime: []
+
+crates: []
+
+host_functions: []
diff --git a/prdoc/pr_1226.prdoc b/prdoc/pr_1226.prdoc
@@ -1,9 +1,9 @@
 title: Removed deprecated `Balances::transfer` and `Balances::set_balance_deprecated` functions.
 
 doc:
-  - audience: Builder
+  - audience: Runtime User
     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.
-    notes: 
+    notes:
       - Use `set_balance_deprecated` instead `force_set_balance` and `transfer_allow_death` instead of `transfer`.
 
 migrations:

diff --git a/prdoc/pr_1234.prdoc b/prdoc/pr_1234.prdoc
@@ -4,7 +4,7 @@
 title: Introduce XcmFeesToAccount fee manager
 
 doc:
-  - audience: Builder
+  - audience: Runtime User
     description: |
       Now all XCM sending, unless done by the system for the system, will be charged delivery fees.
       All runtimes are now configured to send these delivery fees to a treasury account.

diff --git a/prdoc/pr_1255.prdoc b/prdoc/pr_1255.prdoc
@@ -4,7 +4,7 @@
 title: Fix for Reward Deficit in the pool
 
 doc:
-  - audience: Core Dev
+  - audience: Runtime Dev
     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.
     notes:
       - Introduces new call `adjust_pool_deposit` that allows to top up the deficit or withdraw the excess deposit for the pool.
@@ -19,4 +19,4 @@ migrations:
 crates:
   - name: pallet-nomination-pools
 
-host_functions: []
+host_functions: []
diff --git a/prdoc/pr_1408_prodc-introduction.prdoc b/prdoc/pr_1408_prodc-introduction.prdoc
@@ -2,7 +2,7 @@
 title: PRdoc check
 
 doc:
-  - audience: Core Dev
+  - audience: Node Dev
     description: |
       This PRdoc is an **example**.
 

diff --git a/prdoc/pr_1818.prdoc b/prdoc/pr_1818.prdoc
@@ -1,7 +1,7 @@
 title: FRAME pallets warning for unchecked weight witness
 
 doc:
-  - audience: Core Dev
+  - audience: Runtime Dev
     description: |
       FRAME pallets now emit a warning when a call uses a function argument that starts with an underscore in its weight declaration.
 

diff --git a/prdoc/pr_1873.prdoc b/prdoc/pr_1873.prdoc
@@ -1,7 +1,7 @@
 title: Message Queue use proper overweight limit
 
 doc:
-  - audience: Core Dev
+  - audience: Node Dev
     description: |
       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.
 
@@ -10,6 +10,8 @@ migrations:
 
   runtime: []
 
-crates: ["pallet-message-queue", patch]
+crates:
+  - name: pallet-message-queue
+    semver: patch
 
 host_functions: []
diff --git a/prdoc/pr_1921.prdoc b/prdoc/pr_1921.prdoc
@@ -1,7 +1,7 @@
 title: Fix para-scheduler migration
 
 doc:
-  - audience: Core Dev
+  - audience: Runtime Dev
     description: |
       Changing the `MigrateToV1` migration in the `ParachainScheduler` pallet to be truly idempotent. It is achieved by wrapping it in a `VersionedMigration`.
 

diff --git a/prdoc/pr_1946_prdoc_new_schema.prdoc b/prdoc/pr_1946_prdoc_new_schema.prdoc
@@ -0,0 +1,23 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://github.com/paritytech/prdoc
+
+title: New PRDoc Schema
+authors: [ chevdor ]
+tags: [ prdoc, release ]
+
+doc:
+  - audience: Node Dev
+    description:  &desc |
+      The new version of prdoc and the new schema is activated in this PR.
+
+  - audience: Runtime Dev
+    description: *desc
+
+migrations:
+  db: []
+
+  runtime: []
+
+crates: []
+
+host_functions: []