From 37161ee5507fe95275b660cecaf921d3f7fe5328 Mon Sep 17 00:00:00 2001 From: Chevdor 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 000000000000..e677ded8d6cc --- /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 e274b4919473..5c8ee9c9b914 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 20fa1d3a768b..d134188e25df 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 000000000000..e69de29bb2d1 diff --git a/prdoc/pr_1408_prodc-introduction.prdoc b/prdoc/pr_1408_prodc-introduction.prdoc new file mode 100644 index 000000000000..4b10e0fe2e81 --- /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: []