From eaf380aaf5d366d9ad9068126785f3a44cf88c43 Mon Sep 17 00:00:00 2001
From: Chevdor <chevdor@users.noreply.github.com>
Date: Wed, 6 Sep 2023 10:25:47 +0200
Subject: [PATCH] Add PRdoc check (#1408)
* Add test prdoc
* Prepare for the check
* Escape PR number
* Fix conditional step
* Add checkout and actual check
* Cleanup
* Minor fixes
* Add doumentation
* Add more doc
---
.github/workflows/check-prdoc.yml | 51 ++++++++++++++++++++++++++
cumulus/scripts/ci/changelog/README.md | 2 +-
docs/CONTRIBUTING.md | 32 ++++++++++++----
prdoc/.gitkeep | 0
prdoc/pr_1408_prodc-introduction.prdoc | 19 ++++++++++
5 files changed, 96 insertions(+), 8 deletions(-)
create mode 100644 .github/workflows/check-prdoc.yml
create mode 100644 prdoc/.gitkeep
create mode 100644 prdoc/pr_1408_prodc-introduction.prdoc
diff --git a/.github/workflows/check-prdoc.yml b/.github/workflows/check-prdoc.yml
new file mode 100644
index 00000000000..e677ded8d6c
--- /dev/null
+++ b/.github/workflows/check-prdoc.yml
@@ -0,0 +1,51 @@
+name: Check PRdoc
+
+on:
+ pull_request:
+ types: [labeled, opened, synchronize, unlabeled]
+
+env:
+ # todo: switch to paritytech/prdoc once the container is built & published
+ # see https://github.com/paritytech/scripts/pull/595
+ IMAGE: chevdor/prdoc:v0.0.4
+ 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:
+ - name: Pull image
+ run: |
+ echo "Pulling $IMAGE"
+ docker pull $IMAGE
+ docker run --rm $IMAGE --version
+
+ - name: Check if PRdoc is required
+ id: get-labels
+ run: |
+ # Fetch the labels for the PR under test
+ echo "Fetch the labels for $API_BASE/${REPO}/pulls/${GITHUB_PR}"
+ labels=$( curl -H "Authorization: token ${GITHUB_TOKEN}" -s "$API_BASE/${REPO}/pulls/${GITHUB_PR}" | jq '.labels | .[] | .name' | tr "\n" ",")
+ echo "Labels: ${labels}"
+ echo "labels=${labels}" >> "$GITHUB_OUTPUT"
+
+ - name: No PRdoc required
+ if: ${{ contains(steps.get-labels.outputs.labels, 'R0') }}
+ run: |
+ echo "PR detected as silent, no PRdoc is required, exiting..."
+ exit 0
+
+ - name: Checkout repo
+ if: ${{ !contains(steps.get-labels.outputs.labels, 'R0') }}
+ uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac #v4.0.0
+
+ - 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 1408
diff --git a/cumulus/scripts/ci/changelog/README.md b/cumulus/scripts/ci/changelog/README.md
index e274b491947..5c8ee9c9b91 100644
--- a/cumulus/scripts/ci/changelog/README.md
+++ b/cumulus/scripts/ci/changelog/README.md
@@ -61,7 +61,7 @@ all the labels that are used, search for `meta` in the templates. Currently, the
Note that labels with the same letter are mutually exclusive. A PR should not have both `B0` and `B5`, or both `C1` and
`C9`. In case of conflicts, the template will decide which label will be considered.
-## Dev and debuggin
+## Dev and debugging
### Hot Reload
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 20fa1d3a768..d134188e25d 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -80,18 +80,36 @@ Reviews should finish with approval unless there are issues that would result in
The reviewers are also responsible to check:
-a) if a changelog is necessary and attached
-
-b) the quality of information in the changelog file
-
-c) the PR has an impact on docs
-
-d) that the docs team was included in the review process of a docs update
+1. if a changelog is necessary and attached
+1. the quality of information in the changelog file
+1. the PR has an impact on docs
+1. that the docs team was included in the review process of a docs update
**Reviews may not be used as an effective veto for a PR because**:
1. There exists a somewhat cleaner/better/faster way of accomplishing the same feature/fix.
2. It does not fit well with some other contributors' longer-term vision for the project.
+## Documentation
+
+All Pull Requests must contain proper title & description.
+
+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.
+
## Helping out
We use [labels](https://github.com/paritytech/polkadot-sdk/labels) to manage PRs and issues and communicate
diff --git a/prdoc/.gitkeep b/prdoc/.gitkeep
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/prdoc/pr_1408_prodc-introduction.prdoc b/prdoc/pr_1408_prodc-introduction.prdoc
new file mode 100644
index 00000000000..4b10e0fe2e8
--- /dev/null
+++ b/prdoc/pr_1408_prodc-introduction.prdoc
@@ -0,0 +1,19 @@
+# This PR does not need a prdoc but it is provided in order to test
+title: PRdoc check
+
+doc:
+ - audience: Core Dev
+ description: |
+ This PRdoc is an **example**.
+
+ This PR brings support and automated checks for documentation in the form of a
+ [`prdoc`](https://github.com/paritytech/prdoc/) file.
+
+migrations:
+ db: []
+
+ runtime: []
+
+crates: []
+
+host_functions: []
--
GitLab