Initial labels setup for Pezkuwi SDK

.github/workflows/check-gh-pages.yaml

@@ -0,0 +1,54 @@
+name: Check Label Documentation
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    env:
+      MDBOOK_VERSION: 0.4.37 # https://github.com/rust-lang/mdBook/releases
+      TERA_VERSION: 0.2.4 # https://github.com/chevdor/tera-cli/release
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Install Tools
+        run: |
+          wget -O ${{ runner.temp }}/mdbook.tar.gz https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz && \
+          tar xf ${{ runner.temp }}/mdbook.tar.gz && mv mdbook /usr/local/bin && \
+          wget -O ${{ runner.temp }}/tera.deb https://github.com/chevdor/tera-cli/releases/download/v${TERA_VERSION}/tera-cli_linux_amd64.deb && \
+          sudo dpkg -i ${{ runner.temp }}/tera.deb
+
+      - name: Generate the doc
+        run: ./scripts/build-doc.sh
+
+      - name: Check
+        run: ls -al ./docs/src
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Render book
+        run: ./scripts/generate_book.sh
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: ./docs/book

.github/workflows/check-label-rules.yaml

@@ -0,0 +1,34 @@
+name: Check label Rules
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  IMAGE: paritytech/ruled_labels:0.4.0
+
+jobs:
+  check-label-rules:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        repo: [polkadot-sdk]
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+      - name: Pull image
+        run: docker pull $IMAGE
+
+      - name: Check label Rules for ${{ matrix.repo }}
+        env:
+          MOUNT: /work
+          RULES_PATH: ruled_labels
+        run: |
+          docker run --rm -i -v $PWD/${RULES_PATH}/:$MOUNT $IMAGE test -s ${MOUNT}/specs_${{ matrix.repo }}.yaml ${MOUNT}/tests_${{ matrix.repo }}.yaml

.github/workflows/deploy-gh-pages.yaml

@@ -0,0 +1,75 @@
+name: Deploy Label Documentation
+
+on:
+  push:
+    branches: [ main ]
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    env:
+      MDBOOK_VERSION: 0.4.37 # https://github.com/rust-lang/mdBook/releases
+      TERA_VERSION: 0.2.4 # https://github.com/chevdor/tera-cli/release
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Install Tools
+        run: |
+          wget -O ${{ runner.temp }}/mdbook.tar.gz https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz && \
+          tar xf ${{ runner.temp }}/mdbook.tar.gz && mv mdbook /usr/local/bin && \
+          wget -O ${{ runner.temp }}/tera.deb https://github.com/chevdor/tera-cli/releases/download/v${TERA_VERSION}/tera-cli_linux_amd64.deb && \
+          sudo dpkg -i ${{ runner.temp }}/tera.deb
+
+      - name: Generate the doc
+        run: ./scripts/build-doc.sh
+
+      - name: Check
+        run: ls -al ./docs/src
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Render book
+        run: ./scripts/generate_book.sh
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: ./docs/book
+
+  # Deployment job
+  deploy:
+    # this job will fail unless we are in the main branch
+    # so we skip the job for other branches such as PRs.
+    if: ${{ github.ref == 'refs/heads/main' }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -0,0 +1 @@
+*.deb

CODEOWNERS

@@ -0,0 +1,21 @@
+# Lists some code owners.
+#
+# A codeowner just oversees some part of the codebase. If an owned file is changed then the
+# corresponding codeowner receives a review request. An approval of the codeowner might be
+# required for merging a PR (depends on repository settings).
+#
+# For details about syntax, see:
+# https://help.github.com/en/articles/about-code-owners
+# But here are some important notes:
+#
+# - Glob syntax is git-like, e.g. `/core` means the core directory in the root, unlike `core`
+#   which can be everywhere.
+# - Multiple owners are supported.
+# - Either handle (e.g, @github_user or @github_org/team) or email can be used. Keep in mind,
+#   that handles might work better because they are more recognizable on GitHub,
+#   you can use them for mentioning unlike an email.
+# - The latest matching rule, if multiple, takes precedence.
+
+# CI
+/.github/ @pezkuwichain/ci
+* @the-right-joyce

README.md

@@ -0,0 +1,8 @@
+# labels
+
+The repo contains specifications related to labels for the `polkadot-sdk` repo.
+
+It uses [ruled_labels](https://github.com/pezkuwichain/ruled_labels) to define the rules, requirements and interactions between labels.
+The rules and tests are for all repos the same, only the labels differ for each repo.
+
+For more information, check out the generated documentation at [https://pezkuwichain.github.io/labels](https://pezkuwichain.github.io/labels).

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/src/SUMMARY.md

@@ -0,0 +1,7 @@
+# Summary
+
+[Home](HOME.md)
+
+- [Respositories](#)
+  - [Polkadot SDK](doc_polkadot-sdk.md)
+- [FAQ](faq.md)

docs/src/book.toml

@@ -0,0 +1,12 @@
+[book]
+authors = ["Chevdor"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Labels"
+
+[output.html]
+site-url = "/labels/"
+git-repository-url = "https://github.com/paritytech/labels"
+git-repository-icon = "fa-github"
+edit-url-template = "https://github.com/paritytech/labels/edit/main/{path}"

docs/src/faq.md

@@ -0,0 +1,31 @@
+# FAQ
+
+## How is a label interpreted ?
+
+You may see labels defined as `S0-design`. It is made of a label code: `S`, a number: `0` and some description.
+The rules **only apply to the part of the label without the description and the label above will simply be considered as `S0`.
+Should the description change, the rules would remain unaffected.
+
+## What are rules ?
+
+Rules are defined in a YAML files and describe:
+- the name of the rule
+- the conditions of the rule (for instance, some rules only apply if a specific label is present)
+- the conditions for a set of labels to be valid. For instance, you will not be able to have `C1-low` and `C5-high` for a given PR. You will have to chose one or the other and the rules will enforce this
+
+## Where can I find the source of the rules ?
+
+Look for the `specs_<name>.yaml` files in [here](https://github.com/paritytech/labels/tree/main/ruled_labels).
+
+## Are there tests to check those rules ?
+
+Absolutly, look for the `tests_<name>.yaml` files in [here](https://github.com/paritytech/labels/tree/main/ruled_labels).
+
+## Where can I report issues/doubts I have about some rules ?
+
+You can open a new issue in the [labels repository](https://github.com/paritytech/labels/issues).
+
+## What happens when rules fail ?
+
+If you label your PR with an invalid set of labels, the CI will fail and tell you what the issue is.
+You can see an example [here](https://github.com/paritytech/cumulus/actions/runs/4362797055/jobs/7628115688) where a `B` label was missing.

justfile

@@ -0,0 +1,15 @@
+# List available commands
+_default:
+  just --choose --chooser "fzf +s -x --tac --cycle"
+
+help:
+	just --list
+
+# Generate documentation
+doc:
+  ./scripts/build-doc.sh
+
+# Generate the md book
+book: doc
+  ./scripts/generate_book.sh
+  open docs/book/index.html

ruled_labels/specs_pezkuwi-sdk.yaml

@@ -0,0 +1,184 @@
+name: paritytech/pezkuwi-sdk
+description: Import on 2023-08-26
+version: 0.0.2
+
+codes:
+  - code: A
+    name: Action
+    description: Used with GHA and trigger a certain process.
+  - code: C
+    name: Contribution
+    description: Labels used for contributions.
+  - code: D
+    name: Difficulty
+    description: Difficulty of the issues, also used for contributions.
+  - code: I
+    name: Issues
+    description: Categorisation of issues.
+  - code: R
+    name: Release
+    description: Used for creating the release notes.
+  - code: T
+    name: Topics
+    description: PR/Issue is related to this topic.
+
+labels:
+  - name: A0-needs_burnin
+    description: Pull request needs to be tested on a live validator node before merge. DevOps team is notified via matrix.
+    color: c7def8
+  - name: A1-insubstantial
+    description: Pull request requires no code review (e.g., a sub-repository hash update).
+    color: C6C7F8
+  - name: A2-stale
+    description: Pull request did not receive any updates in a long time. No review needed at this stage. Close it.
+    color: F2C5F8
+  - name: A3-backport
+    description: Pull request is already reviewed well in another branch.
+    color: F8C5E7
+  - name: A4-backport-stableYYMM
+    description: Pull request must be backported to the relevant maintained release (e.g stable2506, stable2509, etc.).
+    color: C5DEF5
+  - name: A5-run-CI
+    description: Run CI on draft PR
+    color: C5DEF5
+  - name: C1-mentor
+    description: A task where a mentor is available. Please indicate in the issue who the mentor could be.
+    color: "5319e7"
+  - name: C2-good-first-issue
+    description: A task for a first time contributor to become familiar with the Polkadot-SDK.
+    color: 7CB9E8
+  - name: C3-og-rust-bounty
+    description: A task rewarded by the OG Rust bounty for successful completion. See https://ogrust.com/
+    color: e87cb9
+  - name: D0-easy
+    description: Can be fixed primarily by duplicating and adapting code by an intermediate coder.
+    color: eeeeee
+  - name: D1-medium
+    description: Can be fixed by a coder with good Rust knowledge but little knowledge of the codebase.
+    color: eebb00
+  - name: D2-substantial
+    description: Can be fixed by an experienced coder with a working knowledge of the codebase.
+    color: D4C5F9
+  - name: D3-involved
+    description: Can be fixed by an expert coder with good knowledge of the codebase.
+    color: E99695
+  - name: I0-panic
+    description: The node panics and exits without proper error handling.
+    color: 17b25d
+  - name: I1-security
+    description: The node fails to follow expected, security-sensitive, behaviour.
+    color: d93f0b
+  - name: I2-bug
+    description: The node fails to follow expected behavior.
+    color: "249899"
+  - name: I3-annoyance
+    description: The node behaves within expectations, however this “expected behaviour” itself is at issue.
+    color: D6075D
+  - name: I4-refactor
+    description: Code needs refactoring.
+    color: 0075ca
+  - name: I5-enhancement
+    description: An additional feature request.
+    color: c2e0c6
+  - name: I6-meta
+    description: A specific issue for grouping tasks or bugs of a specific category.
+    color: a2eeef
+  - name: I7-duplicate
+    description: Issue is a duplicate. Closer should comment with a link to the duplicate.
+    color: D62209
+  - name: I8-wont_fix
+    description: Issue might be invalid or this project will not address it. Closer should comment why.
+    color: FB3701
+  - name: I9-optimisation
+    description: An enhancement to provide better overall performance in terms of time-to-completion for a task.
+    color: c5def5
+  - name: I10-unconfirmed
+    description: Issue might be valid, but it's not yet known.
+    color: 723bf6
+  - name: R0-no-crate-publish-required
+    description: The change does not require any crates to be re-published.
+    color: f9f0f4
+  - name: R1-breaking_change
+    description: This PR introduces a breaking change and should be highlighted in the upcoming release.
+    color: f9d0e0
+  - name: T0-node
+    description: This PR/Issue is related to the topic “node”.
+    color: fbffe0
+  - name: T1-FRAME
+    description: This PR/Issue is related to core FRAME, the framework.
+    color: F5FCE6
+  - name: T2-pallets
+    description: This PR/Issue is related to a particular pallet.
+    color: 7962d6
+  - name: T3-RPC_API
+    description: This PR/Issue is related to RPC APIs.
+    color: 635b61
+  - name: T4-runtime_API
+    description: This PR/Issue is related to runtime APIs.
+    color: 009B40
+  - name: T5-host_functions
+    description: This PR/Issue is related to host functions.
+    color: E86C7A
+  - name: T6-XCM
+    description: This PR/Issue is related to XCM.
+    color: 006b75
+  - name: T7-smart_contracts
+    description: This PR/Issue is related to smart contracts.
+    color: 0C7BAD
+  - name: T8-polkadot
+    description: This PR/Issue is related to/affects the Polkadot network.
+    color: c90076
+  - name: T9-cumulus
+    description: This PR/Issue is related to cumulus.
+    color: 6a329f
+  - name: T10-tests
+    description: This PR/Issue is related to tests.
+    color: 6C9C98
+  - name: T11-documentation
+    description: This PR/Issue is related to documentation.
+    color: f48a75
+  - name: T12-benchmarks
+    description: This PR/Issue is related to benchmarking and weights.
+    color: 5319e7
+  - name: T13-deprecation
+    description: The current issue/pr is, or should be, part of a deprecation process.
+    color: 5319e7
+  - name: T14-system_parachains
+    description: This PR/Issue is related to system parachains.
+    color: 0C7BAD
+  - name: T15-bridges
+    description: This PR/Issue is related to bridges.
+    color: F5FCE6
+  - name: T16-async_backing
+    description: Issues related to asynchronous backing.
+    color: E97042
+  - name: T17-primitives
+    description: Changes to primitives that are not covered by any other label.
+    color: 006b75
+  - name: T18-zombienet_tests
+    description: Trigger zombienet CI tests.
+    color: E84D6D
+  - name: T19-skip-zombienet_tests
+    description: Skip triggering of zombienet CI tests.
+    color: BAD28F
+
+rules:
+  - name: Require at least one topic
+    id: multiple_t
+    tags:
+    spec:
+      require: !some_of [T*]
+
+  - name: Allow only one difficulty label
+    id: single_d
+    tags:
+    spec:
+      when: !some_of [D*]
+      require: !one_of [D*]
+
+  - name: Enforce R0
+    id: enforce_r0
+    tags:
+    spec:
+      when: !some_of [A1]
+      require: !all_of [R0]

ruled_labels/tests_pezkuwi-sdk.yaml

@@ -0,0 +1,45 @@
+name: Polkadot SDK ruled-labels test cases
+spec_file: specs_pezkuwi-sdk.yaml
+
+specs:
+  - name: Pass - One topic
+    filter:
+      id: [ multiple_t]
+    labels: [ R1, C1, D1, T4 ]
+    expected: true
+
+  - name: Fail - Require topic label
+    filter:
+      id: [ multiple_t ]
+    labels: [ A1 ]
+    expected: false
+
+  - name: Pass - Multiple topics
+    filter:
+      id: [ multiple_t ]
+    labels: [ A1, R0, T2, T10 ]
+    expected: true
+
+  - name: Fail - Multiple difficulty labels
+    filter:
+      id: [ single_d ]
+    labels: [ A1, D0, D2, T10 ]
+    expected: false
+
+  - name: Pass - Single difficulty label
+    filter:
+      id: [ single_d ]
+    labels: [ R0, D3, T10 ]
+    expected: true
+  
+  - name: Pass - A1 and R0
+    filter:
+      id: [ enforce_r0 ]
+    labels: [ A1, D3, R0 ]
+    expected: true
+
+  - name: Fail - R0 missing
+    filter:
+      id: [ enforce_r0 ]
+    labels: [ A1, T9, D2 ]
+    expected: false

scripts/build-doc.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+export DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+export COMMIT=$(git rev-parse HEAD)
+
+mkdir -p ./docs/src
+
+repo=$1
+repo=${repo:-"polkadot-sdk"}
+
+for chain in $repo; do
+    echo "Generating doc for $chain..."
+    tera --include --env --env-key env --template templates/template.md.tera ruled_labels/specs_${chain}.yaml >./docs/src/doc_${chain}.md
+done

scripts/generate_book.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# Generate date, commit and footer
+export DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+export COMMIT=$(git rev-parse HEAD)
+
+tera --template templates/home.md.tera --env-only --include --env --env-key env > docs/src/HOME.md
+
+mdbook build docs/
+
+echo "You may now open your book with:"
+echo "open docs/book/index.html"

templates/footer.md.tera

@@ -0,0 +1,2 @@
+
+Last updated: {{ env.DATE | date(format="%Y-%m-%d %H:%M") }} - commit [`{{ env.COMMIT | truncate(length=8) }}`](https://github.com/paritytech/labels/commit/{{ env.COMMIT }})

templates/home.md.tera

@@ -0,0 +1,14 @@
+# Labels
+
+This website provides the documentation about Labels.
+
+The source data can be found in the [`ruled_labels`](../ruled_labels) folder of the repository. It contains the specs and tests as YAML files.
+Those files contain:
+- the list of labels
+- explanations about the label codes (the first letter)
+- the logic ruling whether a set of labels is valid or not
+
+Those rules are processed by [ruled_labels](https://github.com/paritytech/ruled_labels) and **all** rules must be satisfied.
+
+---
+{% include "footer.md.tera" %}

templates/template.md.tera

@@ -0,0 +1,64 @@
+# Label Documentation for the repo `{{ name }}`
+
+This document is generated automatically based on commit `{{ env.COMMIT | truncate(length=8, end="")}}` and was last updated on `{{ env.DATE }}`.
+
+The source data can be found in the [`ruled_labels`](../ruled_labels) folder of the repository. Those rules are processed by
+[ruled_labels](https://github.com/paritytech/ruled_labels) and **all** rules must be satisfied.
+
+## Description
+
+This is the documentation for `{{ name }}` version `v{{ version }}`.
+It contains `{{ labels | length }}` labels and `{{ rules | length }}` rules.
+
+{{ description }}
+
+## Rules
+
+{% for rule in rules -%}
+<!-- {{rule.id}} -->
+- `{{ rule.name }}`
+
+{%- if rule.disabled %}
+⚠️ DISABLED
+{%- endif -%}
+
+{%- if rule.description -%}
+{{ rule.description }}
+{%- endif -%}
+
+{%- if rule.spec %}
+{%- if rule.spec.when %}
+  - when: {{ rule.spec.when|json_encode() }}
+{%- endif %}
+
+{%- if rule.spec.require %}
+  - require: {{ rule.spec.require|json_encode() }}
+{%- endif %}
+{%- endif %}
+
+{% endfor -%}
+
+{% if rule.spec.exclude %}
+- Exclude:
+{% for pat in rule.spec.exclude %}
+  - {{ pat }}
+{%- endfor %}{% endif %}
+
+## Labels
+
+{%- set_global current_code = '' -%}
+{% for label in labels | sort(attribute="name") -%}
+
+{%- set code = label.name | truncate(length=1, end="") -%}
+{%- if code != current_code -%}
+{%- set_global current_code = code -%}
+{% for c in codes | filter(attribute="code", value=code) %}
+### `{{ c.code }}␣` - {{ c.name }}: {{c.description}}
+{% endfor %}
+{%- endif -%}
+
+- `{{ label.name }}`: {{ label.description }}
+{% endfor %}
+
+---
+{% include "footer.md.tera" %}