commit 5692f6a0a36a0ee606c832cd069bae2096deabc5 Author: Kurdistan Tech Ministry Date: Thu Nov 27 16:52:00 2025 +0300 Initial labels setup for Pezkuwi SDK diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..2135c94 Binary files /dev/null and b/.DS_Store differ diff --git a/.github/workflows/check-gh-pages.yaml b/.github/workflows/check-gh-pages.yaml new file mode 100644 index 0000000..4f1e503 --- /dev/null +++ b/.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 diff --git a/.github/workflows/check-label-rules.yaml b/.github/workflows/check-label-rules.yaml new file mode 100644 index 0000000..03ce0e1 --- /dev/null +++ b/.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 diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml new file mode 100644 index 0000000..e946a29 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c00df13 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.deb diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..d6861a0 --- /dev/null +++ b/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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..ed5993d --- /dev/null +++ b/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). diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..bf186a5 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +[Home](HOME.md) + +- [Respositories](#) + - [Polkadot SDK](doc_polkadot-sdk.md) +- [FAQ](faq.md) diff --git a/docs/src/book.toml b/docs/src/book.toml new file mode 100644 index 0000000..f1fe0a2 --- /dev/null +++ b/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}" diff --git a/docs/src/faq.md b/docs/src/faq.md new file mode 100644 index 0000000..e81e76a --- /dev/null +++ b/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_.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_.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. diff --git a/justfile b/justfile new file mode 100644 index 0000000..c8d2df2 --- /dev/null +++ b/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 diff --git a/ruled_labels/specs_pezkuwi-sdk.yaml b/ruled_labels/specs_pezkuwi-sdk.yaml new file mode 100644 index 0000000..0469d2b --- /dev/null +++ b/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] diff --git a/ruled_labels/tests_pezkuwi-sdk.yaml b/ruled_labels/tests_pezkuwi-sdk.yaml new file mode 100644 index 0000000..9331665 --- /dev/null +++ b/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 diff --git a/scripts/build-doc.sh b/scripts/build-doc.sh new file mode 100755 index 0000000..31b926e --- /dev/null +++ b/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 diff --git a/scripts/generate_book.sh b/scripts/generate_book.sh new file mode 100755 index 0000000..346b8ba --- /dev/null +++ b/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" diff --git a/templates/footer.md.tera b/templates/footer.md.tera new file mode 100644 index 0000000..f237e7e --- /dev/null +++ b/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 }}) diff --git a/templates/home.md.tera b/templates/home.md.tera new file mode 100644 index 0000000..cc2ef47 --- /dev/null +++ b/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" %} diff --git a/templates/template.md.tera b/templates/template.md.tera new file mode 100644 index 0000000..e94efee --- /dev/null +++ b/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.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" %}