diff --git a/.claude/skills/labels/SKILL.md b/.claude/skills/labels/SKILL.md new file mode 100644 index 0000000000..e12153f87a --- /dev/null +++ b/.claude/skills/labels/SKILL.md @@ -0,0 +1,35 @@ +--- +name: labels +description: Label pull requests and issues in this repository, and add, rename or retire a label. Use when opening a pull request, filing an issue, asking for an app build, marking work as blocked, triaging, or when a task mentions a label. Labels are defined as code in .github/labels.yml, so a label is never created by hand. +--- + +# Labels + +[docs/labels.md](../../../docs/labels.md) owns the system: every family, what each label means, and what is automatic. Read it for anything this file does not answer. + +## Opening a pull request + +- Do not add `area:` or `size:` labels. A pull request carries no area, and `pr-triage.yml` sets the size from the lines changed. +- Do not set `status:waiting-on-review`; `pr-triage.yml` sets it whenever a pull request that is not a draft has no status. +- Add a `ci:` label only to get what it runs, and only when the change needs it: `ci:ios-simulator` or `ci:ios-device` for the iOS app, `ci:android-device` for an APK, `ci:android-emulator-tests`, `ci:host-playground-e2e`. Each one starts macOS or emulator jobs on every later push, so do not add them by default. +- Add `ci:no-changeset` only when the change ships nothing, as docs/RELEASE_PROCESS.md describes. +- To label the issue the pull request finishes, write `Closes #N` in the body. The issue gets its `area:` labels when the pull request merges. + +## While it is open + +- Keep one `status:` label, named for who acts next: `status:waiting-on-author` after requesting changes, `status:ready-to-merge` once approved, `status:blocked` when something else has to land first, with a comment saying what. +- Add a `needs:` label when work is blocked on something other than code: `needs:spec`, `needs:decision` or `needs:UI`. Remove it once resolved. + +## Filing an issue + +- Add `area:` labels for what it touches, and a `spa:` label when a product needs it. +- Type, status, priority and target date are issue fields, not labels. + +## Adding, renaming or retiring a label + +- Never create, rename or delete a label with `gh label` or the web UI. Edit `.github/labels.yml` in a pull request; `scripts/sync-labels.py` applies it when the pull request merges. +- Name it `family:value`, lowercase with hyphens, in an existing family. Give it a color, a description saying when to use it, a `target` and an `addedBy`. +- To rename, put the old name under `previously`; the label stays on everything that carries it. To delete, move it under `retired` with a reason. A label whose replacement is not decided goes under `pending`. +- If a workflow, script, template or doc names the label, change it in the same pull request, so the label and its users land together. `rg` for the old name across `.github`, `scripts`, `.claude` and the docs. +- Run `python3 scripts/sync-labels.py` to see the plan against the live labels. It only reads. Never pass `--apply`; the push to main does that. +- `diagnosis-report` keeps its name: deployed copies of the playground open issues with it. diff --git a/.claude/skills/rfc-issue/SKILL.md b/.claude/skills/rfc-issue/SKILL.md index 7c5627be77..8f6f71ee66 100644 --- a/.claude/skills/rfc-issue/SKILL.md +++ b/.claude/skills/rfc-issue/SKILL.md @@ -1,6 +1,6 @@ --- name: rfc-issue -description: Write the tracking issue for an RFC — a short Description / Motivation / Requirements / Tasks body labeled `rfc`, written either from an RFC document already in review or from notes when no RFC exists yet. Use for "open a tracking issue for this RFC", "create issues for the open RFCs", or when an idea needs an RFC that nobody has drafted. +description: Write the tracking issue for an RFC — a short Description / Motivation / Requirements / Tasks body labeled `area:rfc`, written either from an RFC document already in review or from notes when no RFC exists yet. Use for "open a tracking issue for this RFC", "create issues for the open RFCs", or when an idea needs an RFC that nobody has drafted. argument-hint: [RFC PR number, RFC path, or a description of the idea] --- @@ -18,7 +18,7 @@ remote permission` becomes `RFC: Credential-endpoint remote permission`. The num belongs to the document: it changes when the document is renumbered and it collides between RFCs in flight. -**Label** — `rfc`. +**Label** — `area:rfc`. **Body** — four sections, nothing else: @@ -103,8 +103,8 @@ an RFC amending `product-manifest.md` gets its own issue, but a second PR agains same amendment does not. ```bash -gh issue list --label rfc --state all --limit 100 -gh issue create --title "RFC: " --body-file <path> --label rfc +gh issue list --label area:rfc --state all --limit 100 +gh issue create --title "RFC: <Title>" --body-file <path> --label area:rfc ``` ## Related diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 34f4baf700..cd4c2102d8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,6 +1,6 @@ # Reviewers requested from the paths a pull request touches. # -# The same roots drive labelling in .github/labeler.yml. The two are different +# The same roots drive the areas in .github/areas.yml. The two are different # formats and cannot be one file, so scripts/check-path-routing.py holds them to # the same set and CI runs it. # diff --git a/.github/PULL_REQUEST_TEMPLATE/design.md b/.github/PULL_REQUEST_TEMPLATE/design.md index 34542cc79a..11597d63de 100644 --- a/.github/PULL_REQUEST_TEMPLATE/design.md +++ b/.github/PULL_REQUEST_TEMPLATE/design.md @@ -8,7 +8,6 @@ - [ ] Added or updated file in `docs/design/` - [ ] Included YAML frontmatter with title, type, status, author, created, and pr fields -- [ ] Added label: `design-doc` ### Changes diff --git a/.github/PULL_REQUEST_TEMPLATE/feature.md b/.github/PULL_REQUEST_TEMPLATE/feature.md index 44a8add0f4..a637eb5568 100644 --- a/.github/PULL_REQUEST_TEMPLATE/feature.md +++ b/.github/PULL_REQUEST_TEMPLATE/feature.md @@ -8,7 +8,6 @@ - [ ] Added `docs/features/short-descriptive-name.md` with completed frontmatter - [ ] Updated `docs/features/_index.md` with a link to the new proposal -- [ ] Added labels: `feature-request`, `proposal` ### Use Cases diff --git a/.github/PULL_REQUEST_TEMPLATE/rfc.md b/.github/PULL_REQUEST_TEMPLATE/rfc.md index ed3800ce9b..6737d20aa2 100644 --- a/.github/PULL_REQUEST_TEMPLATE/rfc.md +++ b/.github/PULL_REQUEST_TEMPLATE/rfc.md @@ -9,7 +9,6 @@ - [ ] Added `docs/rfcs/<slug>.md` (no number — CI assigns one on merge) - [ ] Filled all RFC sections (Summary, Motivation, Detailed Design, Drawbacks, Alternatives, Unresolved Questions) - [ ] Updated Rust traits in `rust/crates/truapi/` -- [ ] Added label: `rfc` ### Motivation diff --git a/.github/areas.yml b/.github/areas.yml new file mode 100644 index 0000000000..052d72f5f9 --- /dev/null +++ b/.github/areas.yml @@ -0,0 +1,47 @@ +# Which paths belong to which area. issue-areas.yml reads this to label the +# issues a pull request closes; new pull requests carry no area themselves. Every +# label here is defined in .github/labels.yml. +# +# The same paths decide who is asked to review in .github/CODEOWNERS. The two +# files are different formats, so scripts/check-path-routing.py holds them to the +# same set of roots and CI runs it. Change one and the check tells you about the +# other. +# +# Globs: `**` matches across directories, `*` within one. A glob with no slash, +# like `*.md`, matches at the repository root only. A glob starting with `!` takes +# the paths it matches out of that area. +# +# Keep it flat: a quoted label, then one quoted glob per line. issue-areas.yml +# reads it without a YAML parser. + +"area:rfc": + - "docs/rfcs/**" + +"area:docs": + - "docs/**" + - "*.md" + - "!docs/rfcs/**" + +"area:ci": + - ".github/workflows/**" + - ".github/actions/**" + +"area:js": + - "js/**" + - "playground/**" + - "explorer/**" + +# The core reaches every host at once, so a change here is the most expensive +# one to get wrong. +"area:core": + - "rust/crates/**" + +# The hosts are apart rather than together. An iOS-only change and an +# Android-only change are reviewed by different people and break differently. +"area:ios": + - "hosts/ios/**" + - "ios/**" + +"area:android": + - "hosts/android/**" + - "android/**" diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 6b4ace2db2..732a764610 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,6 +5,10 @@ version: 2 updates: - package-ecosystem: github-actions directory: / + # Set explicitly, because its default ecosystem label is not one + # .github/labels.yml defines. + labels: + - dependencies schedule: interval: weekly cooldown: diff --git a/.github/labeler.yml b/.github/labeler.yml deleted file mode 100644 index 335b576a9c..0000000000 --- a/.github/labeler.yml +++ /dev/null @@ -1,54 +0,0 @@ -# Labels applied from the paths a pull request touches. Every label here already -# exists in the repository; adding one means adding it there first. -# -# The same paths drive reviewer assignment in .github/CODEOWNERS. The two files -# are different formats and cannot be one file, so scripts/check-path-routing.py -# holds them to the same set of roots and CI runs it. Change one and the check -# tells you about the other. - -rfc: - - changed-files: - - any-glob-to-any-file: - - "docs/rfcs/**" - -documentation: - - changed-files: - - any-glob-to-any-file: - - "docs/**" - - "*.md" - -github_actions: - - changed-files: - - any-glob-to-any-file: - - ".github/workflows/**" - - ".github/actions/**" - -javascript: - - changed-files: - - any-glob-to-any-file: - - "js/**" - - "playground/**" - - "explorer/**" - -# The core reaches every host at once, so a change here is the most expensive -# one to get wrong. It carried no label at all, which left it indistinguishable -# from a documentation edit on the pull request list. -rust: - - changed-files: - - any-glob-to-any-file: - - "rust/crates/**" - -# The hosts are labelled apart rather than together. An iOS-only change and an -# Android-only change are reviewed by different people and break differently, -# and a single host-work label said neither. -host-ios: - - changed-files: - - any-glob-to-any-file: - - "hosts/ios/**" - - "ios/**" - -host-android: - - changed-files: - - any-glob-to-any-file: - - "hosts/android/**" - - "android/**" diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000000..9c00aea1f7 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,250 @@ +# Every label in this repository, as data. docs/labels.md explains the system; +# this file is what scripts/sync-labels.py applies. +# +# A pull request that changes this file gets a dry run listing what would be +# created, renamed, recoloured, merged and deleted. The push to main applies it. +# +# Fields: +# name The label as it appears on GitHub, as family:value. +# color Six hex digits, no leading #. +# description Shown in the label picker. Say when to use it, not what it is. +# target prs, issues or both: where the label belongs. +# addedBy humans, or the workflow that applies it. +# previously Labels this one replaces. When this label does not exist yet, +# the first that does is renamed in place, so everything carrying +# it keeps it. Any other is merged: its issues and pull requests +# get this label, then the old one is deleted. +# +# A label that exists on GitHub and appears nowhere here is reported, not +# deleted. Only the names under `retired` are deleted. + +labels: + # area: what an issue touches. issue-areas.yml adds them to the issues a pull + # request closes when it merges, from the paths in .github/areas.yml; they can + # also be set by hand when the issue is filed. New pull requests do not carry + # them; older ones keep the ones they had. + - name: "area:core" + color: "1d76db" + description: "Touches the Rust core under rust/crates" + target: issues + addedBy: issue-areas, humans + previously: [rust] + - name: "area:ios" + color: "1d76db" + description: "Touches the iOS host app or the iOS packages" + target: issues + addedBy: issue-areas, humans + previously: [host-ios] + - name: "area:android" + color: "1d76db" + description: "Touches the Android host app or the Android packages" + target: issues + addedBy: issue-areas, humans + previously: [host-android] + - name: "area:js" + color: "1d76db" + description: "Touches the TypeScript packages, the playground or the explorer" + target: issues + addedBy: issue-areas, humans + previously: [javascript] + - name: "area:ci" + color: "1d76db" + description: "Touches workflows or actions under .github" + target: issues + addedBy: issue-areas, humans + previously: [github_actions] + - name: "area:docs" + color: "1d76db" + description: "Touches documentation" + target: issues + addedBy: issue-areas, humans + previously: [documentation] + - name: "area:rfc" + color: "1d76db" + description: "An RFC, or work tracked by one under docs/rfcs" + target: issues + addedBy: issue-areas, humans + previously: [rfc] + + # needs: what is blocking the work. On issues and pull requests alike. + - name: "needs:decision" + color: "b60205" + description: "Blocked on a human decision, not on work" + target: both + addedBy: humans + - name: "needs:spec" + color: "d93f0b" + description: "Accepted but has no written design or RFC body yet" + target: both + addedBy: humans + - name: "needs:UI" + color: "f9d0c4" + description: "Cannot be implemented without UI design, and it's pending" + target: both + addedBy: humans + + # spa: which product needs it. Set by whoever files the issue. + - name: "spa:humanity" + color: "cbf5b0" + description: "Humanity SPA" + target: issues + addedBy: humans + - name: "spa:jollity" + color: "db4ac3" + description: "Jollity SPA" + target: issues + addedBy: humans + - name: "spa:scarcity" + color: "9e315b" + description: "Scarcity SPA" + target: issues + addedBy: humans + - name: "spa:seity" + color: "8d3a8f" + description: "Seity SPA work (user ID)" + target: issues + addedBy: humans + + # status: who acts next on a pull request. One at a time. pr-triage.yml sets + # the first one on a pull request that has none. + - name: "status:waiting-on-review" + color: "fbca04" + description: "Ready for a reviewer" + target: prs + addedBy: pr-triage + - name: "status:waiting-on-author" + color: "fef2c0" + description: "The author has changes to make before the next review" + target: prs + addedBy: humans + - name: "status:ready-to-merge" + color: "0e8a16" + description: "Approved and waiting only to be queued" + target: prs + addedBy: humans + - name: "status:blocked" + color: "b60205" + description: "Cannot move until something else lands; say what in a comment" + target: prs + addedBy: humans + + # size: how much a reviewer has to read. pr-triage.yml sets it from the lines + # changed, leaving out generated files, lockfiles and database schemas. + - name: "size:XS" + color: "ededed" + description: "Fewer than 10 lines changed" + target: prs + addedBy: pr-triage + - name: "size:S" + color: "d4d4d4" + description: "10 to 29 lines changed" + target: prs + addedBy: pr-triage + - name: "size:M" + color: "bdbdbd" + description: "30 to 99 lines changed" + target: prs + addedBy: pr-triage + - name: "size:L" + color: "9e9e9e" + description: "100 to 499 lines changed" + target: prs + addedBy: pr-triage + - name: "size:XL" + color: "757575" + description: "500 to 999 lines changed; consider splitting" + target: prs + addedBy: pr-triage + - name: "size:XXL" + color: "424242" + description: "1000 lines or more; split it, or say in the description why it cannot be" + target: prs + addedBy: pr-triage + + # ci: asks for a build or changes what a check expects. Each starts as soon as + # it is added and follows the branch from then on. + - name: "ci:ios-simulator" + color: "c5def5" + description: "Build the iOS app, run its tests and attach a simulator build" + target: prs + addedBy: humans + previously: [ios-simulator-build] + - name: "ci:ios-device" + color: "c5def5" + description: "Attach a signed iOS build that installs on a registered device" + target: prs + addedBy: humans + previously: [ios-device-build] + - name: "ci:android-device" + color: "c5def5" + description: "Attach an Android APK that installs on any phone" + target: prs + addedBy: humans + previously: [android-device-build] + - name: "ci:android-emulator-tests" + color: "c5def5" + description: "Run the Android instrumented tests on an emulator" + target: prs + addedBy: humans + previously: [android-instrumented-tests] + - name: "ci:host-playground-e2e" + color: "c5def5" + description: "Run the host-playground e2e inside the iOS and Android apps" + target: prs + addedBy: humans + previously: [host-playground-e2e] + - name: "ci:no-changeset" + color: "c5def5" + description: "Changes no published artifact, so the changeset check passes without one" + target: prs + addedBy: humans + previously: [no-changeset] + + # Applied by automation that names them, so they stay outside the families. + - name: "backport-host" + color: "0e8a16" + description: "A vendored host tree is behind its source; the work order says what to bring in" + target: prs + addedBy: backport-host + - name: "dependencies" + color: "0366d6" + description: "Pull requests that update a dependency file" + target: prs + addedBy: dependabot, update-chain-specs + # The playground opens diagnosis issues with this label in a pre-filled URL, + # so renaming it breaks every deployed copy of the playground. + - name: "diagnosis-report" + color: "1d76db" + description: "Playground diagnosis report to ingest into explorer/diagnosis-reports" + target: issues + addedBy: playground + +# Deleted when this file is applied. +retired: + - name: invalid + reason: "Close the issue as not planned instead" + - name: w3s + reason: "Release-specific, and that release has passed" + - name: post-w3s + reason: "Release-specific, and that release has passed" + +# Left exactly as they are until their replacement is decided. +pending: + - name: Epic + reason: "An issue type, or a feature with sub-issues" + - name: enhancement + reason: "Becomes the Feature issue type" + - name: "feature request" + reason: "Becomes the Feature issue type" + - name: proposal + reason: "Becomes the Feature issue type" + - name: "R2 blocker" + reason: "A target date, a field or a label, still to decide" + - name: "R3+" + reason: "A target date, a field or a label, still to decide" + - name: host-work + reason: "An area for both hosts, or retired" + - name: python + reason: "A language label: merge into an area as rust and javascript were, or retire" + - name: Stability + reason: "A theme that crosses areas, so not an area; a family or retired" diff --git a/.github/workflows/android-device-preview.yml b/.github/workflows/android-device-preview.yml index 1937531666..5526f044e8 100644 --- a/.github/workflows/android-device-preview.yml +++ b/.github/workflows/android-device-preview.yml @@ -3,7 +3,7 @@ # Its own workflow rather than a job in ci.yml, because starting it needs the # `labeled` event and adding that to ci.yml would rerun every gate each time # any label changed. on-label.yml calls it for a pull request labelled -# android-device-build. +# ci:android-device. # # The artifact is attached to the run and nothing else. Unlike the iOS device # preview there is no provisioning to do: an Android debug build installs on diff --git a/.github/workflows/android-instrumented-tests.yml b/.github/workflows/android-instrumented-tests.yml index 7c1f70ebd5..1e0041258d 100644 --- a/.github/workflows/android-instrumented-tests.yml +++ b/.github/workflows/android-instrumented-tests.yml @@ -2,7 +2,7 @@ # commit: a cold emulator costs minutes before the first test. # # Started by a label rather than by every push: on-label.yml calls it for a -# pull request labelled android-instrumented-tests. Dispatch exercises the +# pull request labelled ci:android-emulator-tests. Dispatch exercises the # workflow itself without a pull request to carry the label. name: Android instrumented tests diff --git a/.github/workflows/backport-host.yml b/.github/workflows/backport-host.yml index e8182e466c..75f4462d85 100644 --- a/.github/workflows/backport-host.yml +++ b/.github/workflows/backport-host.yml @@ -58,8 +58,6 @@ jobs: env: GH_TOKEN: ${{ github.token }} HOST: ${{ matrix.host }} - # The labels are named for the trees, so this needs no mapping. - HOST_LABEL: host-${{ matrix.host }} steps: # Depth 1. The range below is walked over commits fetched from the source # repository, which this repository's own history plays no part in, and @@ -72,8 +70,9 @@ jobs: id: open_pr run: | set -euo pipefail - existing="$(gh pr list --state open --label backport-host --label "$HOST_LABEL" \ - --json number --jq '.[0].number // ""')" + # The branch names its tree, so it tells this tree's orders apart. + existing="$(gh pr list --state open --label backport-host --json number,headRefName \ + --jq "[.[] | select(.headRefName | startswith(\"hosts/backport-${HOST}-\"))][0].number // \"\"")" if [ -n "$existing" ]; then echo "already=true" >> "$GITHUB_OUTPUT" { @@ -272,7 +271,6 @@ jobs: --head "$BRANCH" \ --title "chore(hosts): backport ${COUNT} commits into hosts/${HOST}" \ --label backport-host \ - --label "$HOST_LABEL" \ --body-file "${RUNNER_TEMP}/pr-body.md")" echo "::notice::${url}" { diff --git a/.github/workflows/build-label-hint.yml b/.github/workflows/build-label-hint.yml index 02909d1b13..6ca3667ffd 100644 --- a/.github/workflows/build-label-hint.yml +++ b/.github/workflows/build-label-hint.yml @@ -62,19 +62,19 @@ jobs: const builds = [ { - label: 'ios-simulator-build', + label: 'ci:ios-simulator', name: 'iOS simulator build', path: /^(hosts\/ios\/|ios\/|Package\.swift$)/, what: 'builds the iOS app and attaches a build for the iOS Simulator on a Mac; its unit tests run on every pull request', }, { - label: 'ios-device-build', + label: 'ci:ios-device', name: 'iOS device build', path: /^(hosts\/ios\/|ios\/|Package\.swift$)/, what: 'attaches a signed build that installs on a registered iPhone or iPad', }, { - label: 'android-device-build', + label: 'ci:android-device', name: 'Android build', path: /^(hosts\/android\/|android\/truapi-host\/)/, what: 'attaches an APK that installs on an Android phone or an emulator', diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 26cac20923..05b31a74bf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -354,7 +354,7 @@ jobs: fi } - gate workflows '^(\.github/workflows/|\.github/actions/|\.github/labeler\.yml$|\.github/CODEOWNERS$|\.github/hosts\.json$|hosts/[a-z]+/\.github/|scripts/(lint-composite-shell|check-path-routing|ci-gates)\.py$)' + gate workflows '^(\.github/workflows/|\.github/actions/|\.github/areas\.yml$|\.github/labels\.yml$|\.github/CODEOWNERS$|\.github/hosts\.json$|hosts/[a-z]+/\.github/|scripts/(lint-composite-shell|check-path-routing|ci-gates)\.py$)' # The packaging path has its own inputs: the archive layout in the # Makefile, the runner bundle, the generated sources cli-dist refuses # to build without, and the dependency set the musl link has to @@ -1170,8 +1170,8 @@ jobs: set -euo pipefail pr="$(gh pr view "$PR_NUMBER" --json title,labels)" - if jq -e '(.title | startswith("release:")) or any(.labels[]; .name == "no-changeset")' <<<"$pr" >/dev/null; then - echo "Release PR or explicit no-changeset opt-out." + if jq -e '(.title | startswith("release:")) or any(.labels[]; .name == "ci:no-changeset")' <<<"$pr" >/dev/null; then + echo "Release PR or an explicit \`ci:no-changeset\` opt-out." exit 0 fi @@ -1180,7 +1180,7 @@ jobs: exit 0 fi - echo "::error::This change reaches a published artifact but adds no changeset, so it would ship undescribed and at a version level chosen by some other change. Run \`npm run changeset\`, or add the \`no-changeset\` label if it genuinely ships nothing." + echo "::error::This change reaches a published artifact but adds no changeset, so it would ship undescribed and at a version level chosen by some other change. Run \`npm run changeset\`, or add the \`ci:no-changeset\` label if it genuinely ships nothing." exit 1 ci-status: diff --git a/.github/workflows/host-playground-e2e.yml b/.github/workflows/host-playground-e2e.yml index 2e591b3de6..25ff02b5f1 100644 --- a/.github/workflows/host-playground-e2e.yml +++ b/.github/workflows/host-playground-e2e.yml @@ -3,7 +3,7 @@ name: host-playground e2e # Runs host-playground inside the iOS and Android host apps built from this commit. # See e2e/host-playground/README.md. # Each nightly calls this for its own platform and commit. on-label.yml calls -# it for both platforms on a pull request labelled host-playground-e2e, never +# it for both platforms on a pull request labelled ci:host-playground-e2e, never # one from a fork. on: workflow_dispatch: diff --git a/.github/workflows/ios-app.yml b/.github/workflows/ios-app.yml index bf10b63558..2832e2120b 100644 --- a/.github/workflows/ios-app.yml +++ b/.github/workflows/ios-app.yml @@ -542,7 +542,7 @@ jobs: retention-days: 3 # An installable build for every commit on a pull request labelled - # ios-simulator-build. The simulator + # ci:ios-simulator. The simulator # slice needs no provisioning profile and no signing identity, so it needs # nothing the build job does not already have, and a reviewer can run the # change rather than read it. @@ -684,7 +684,7 @@ jobs: An arm64 simulator slice, so it needs an Apple Silicon Mac and does not install on a device. Kept for 14 days, after which the link stops - resolving and a new push rebuilds it while \`ios-simulator-build\` is + resolving and a new push rebuilds it while \`ci:ios-simulator\` is set. EOF diff --git a/.github/workflows/ios-device-preview.yml b/.github/workflows/ios-device-preview.yml index 17f9b84e42..ab985fcd81 100644 --- a/.github/workflows/ios-device-preview.yml +++ b/.github/workflows/ios-device-preview.yml @@ -4,7 +4,7 @@ # Its own workflow rather than a job in ios-app.yml, because it exports ad-hoc, # signed by an Apple Distribution certificate against a profile naming # registered devices, and is asked for with a label of its own. on-label.yml -# calls it for a pull request labelled ios-device-build, never one from a fork, +# calls it for a pull request labelled ci:ios-device, never one from a fork, # because the Parity machines are persistent and shared. # # It exports ad-hoc, which is signed by an Apple Distribution certificate diff --git a/.github/workflows/issue-areas.yml b/.github/workflows/issue-areas.yml new file mode 100644 index 0000000000..7876c4d944 --- /dev/null +++ b/.github/workflows/issue-areas.yml @@ -0,0 +1,104 @@ +name: Issue areas + +# Gives an issue the `area:` labels of the pull request that closes it, so the +# issue list can be filtered by area without anyone labelling by hand. New pull +# requests carry no area themselves; docs/labels.md has the system. +# +# It runs when a pull request merges, which is when its closing references take +# effect, so an unmerged or abandoned pull request labels nothing. Only issues it +# closes are labelled: those it names with a closing keyword (`Closes #12`) or +# links under Development. A plain mention such as "part of #12" does not count, +# so an epic does not collect every area its pull requests touch. Labels are only +# ever added, so one set by hand stays. +# +# pull_request_target, so a merged pull request from a fork works too. It reads +# .github/areas.yml from the merge commit and checks out no pull request code. + +on: + pull_request_target: + types: [closed] + +permissions: + contents: read + issues: write + pull-requests: read + +concurrency: + group: issue-areas-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + areas: + name: Label the closed issues by area + if: github.event.pull_request.merged == true + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { owner, repo } = context.repo; + const pr = context.payload.pull_request; + + const { repository } = await github.graphql(` + query($owner: String!, $repo: String!, $number: Int!) { + repository(owner: $owner, name: $repo) { + pullRequest(number: $number) { + closingIssuesReferences(first: 25) { + nodes { number repository { nameWithOwner } } + } + } + } + }`, { owner, repo, number: pr.number }); + const issues = repository.pullRequest.closingIssuesReferences.nodes + .filter(issue => issue.repository.nameWithOwner === `${owner}/${repo}`) + .map(issue => issue.number); + if (issues.length === 0) { + core.info('This pull request closes no issue here.'); + return; + } + + // A glob with `**` matches across directories and `*` within one. + const glob = g => new RegExp('^' + g + .replace(/[.+^${}()|[\]\\]/g, '\\$&') + .replace(/\*\*\//g, '\u0001') + .replace(/\*\*/g, '\0') + .replace(/\*/g, '[^/]*') + .replace(/\?/g, '[^/]') + .replace(/\u0001/g, '(.*/)?') + .replace(/\0/g, '.*') + '$'); + const data = await github.rest.repos.getContent({ + owner, repo, path: '.github/areas.yml', ref: pr.merge_commit_sha, + }).then(r => r.data, e => { if (e.status === 404) return null; throw e; }); + if (!data) { + core.info(`${pr.base.ref} has no .github/areas.yml, so no area applies.`); + return; + } + // The file is flat: an area label, then its globs one per line. A + // glob starting with `!` takes the paths it matches out of the area. + const areas = {}; + let current = null; + for (const raw of Buffer.from(data.content, 'base64').toString().split('\n')) { + const line = raw.replace(/#.*$/, '').trimEnd(); + const label = line.match(/^"([^"]+)":\s*$/); + const path = line.match(/^\s+-\s+"([^"]+)"\s*$/); + if (label) areas[current = label[1]] = { include: [], exclude: [] }; + else if (path && current && path[1].startsWith('!')) areas[current].exclude.push(glob(path[1].slice(1))); + else if (path && current) areas[current].include.push(glob(path[1])); + } + + const files = (await github.paginate(github.rest.pulls.listFiles, { + owner, repo, pull_number: pr.number, per_page: 100, + })).flatMap(f => [f.filename, f.previous_filename].filter(Boolean)); + const labels = Object.keys(areas) + .filter(area => files.some(f => areas[area].include.some(re => re.test(f)) + && !areas[area].exclude.some(re => re.test(f)))); + if (labels.length === 0) { + core.info('No changed path belongs to an area.'); + return; + } + + for (const number of issues) { + await github.rest.issues.addLabels({ owner, repo, issue_number: number, labels }); + core.info(`#${number}: ${labels.join(', ')}`); + } diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml deleted file mode 100644 index 37f0796a2a..0000000000 --- a/.github/workflows/labeler.yml +++ /dev/null @@ -1,27 +0,0 @@ -# Applies labels from the paths a pull request touches, so triage does not depend -# on someone remembering. Configuration lives in .github/labeler.yml. -name: labeler - -# pull_request_target so labels can be applied to pull requests from forks. This -# runs the base branch's configuration and checks out no pull request code, which -# is what makes that trigger safe here. -on: - pull_request_target: - types: [opened, synchronize, reopened] - -permissions: - contents: read - pull-requests: write - -concurrency: - group: labeler-${{ github.event.pull_request.number }} - cancel-in-progress: true - -jobs: - label: - name: Label by path - runs-on: ubuntu-latest - steps: - - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0 - with: - sync-labels: false diff --git a/.github/workflows/on-label.yml b/.github/workflows/on-label.yml index f159674b3c..c1b07a4f23 100644 --- a/.github/workflows/on-label.yml +++ b/.github/workflows/on-label.yml @@ -9,7 +9,7 @@ name: Label builds # # `labeled` fires for every label, so each job matches only its own label being # added. Matching on the label being present would let any other label, added -# by a person or by labeler.yml, start a second run of every labelled job for +# by a person or by pr-triage.yml, start a second run of every labelled job for # the same commit. ci.yml does not run on `labeled`, so a label never reruns the # required checks. # @@ -30,9 +30,9 @@ jobs: name: iOS simulator preview if: >- github.event.pull_request.head.repo.full_name == github.repository - && ((github.event.action == 'labeled' && github.event.label.name == 'ios-simulator-build') + && ((github.event.action == 'labeled' && github.event.label.name == 'ci:ios-simulator') || (github.event.action != 'labeled' - && contains(github.event.pull_request.labels.*.name, 'ios-simulator-build'))) + && contains(github.event.pull_request.labels.*.name, 'ci:ios-simulator'))) concurrency: group: ios-simulator-preview-${{ github.event.pull_request.number }} cancel-in-progress: true @@ -50,9 +50,9 @@ jobs: name: iOS device preview if: >- github.event.pull_request.head.repo.full_name == github.repository - && ((github.event.action == 'labeled' && github.event.label.name == 'ios-device-build') + && ((github.event.action == 'labeled' && github.event.label.name == 'ci:ios-device') || (github.event.action == 'synchronize' - && contains(github.event.pull_request.labels.*.name, 'ios-device-build'))) + && contains(github.event.pull_request.labels.*.name, 'ci:ios-device'))) uses: ./.github/workflows/ios-device-preview.yml secrets: inherit permissions: @@ -64,9 +64,9 @@ jobs: android-device-preview: name: Android device preview if: >- - (github.event.action == 'labeled' && github.event.label.name == 'android-device-build') + (github.event.action == 'labeled' && github.event.label.name == 'ci:android-device') || (github.event.action == 'synchronize' - && contains(github.event.pull_request.labels.*.name, 'android-device-build')) + && contains(github.event.pull_request.labels.*.name, 'ci:android-device')) uses: ./.github/workflows/android-device-preview.yml secrets: inherit permissions: @@ -76,9 +76,9 @@ jobs: android-instrumented-tests: name: Android instrumented tests if: >- - (github.event.action == 'labeled' && github.event.label.name == 'android-instrumented-tests') + (github.event.action == 'labeled' && github.event.label.name == 'ci:android-emulator-tests') || (github.event.action != 'labeled' - && contains(github.event.pull_request.labels.*.name, 'android-instrumented-tests')) + && contains(github.event.pull_request.labels.*.name, 'ci:android-emulator-tests')) uses: ./.github/workflows/android-instrumented-tests.yml secrets: inherit @@ -90,9 +90,9 @@ jobs: name: host-playground e2e if: >- github.event.pull_request.head.repo.full_name == github.repository - && ((github.event.action == 'labeled' && github.event.label.name == 'host-playground-e2e') + && ((github.event.action == 'labeled' && github.event.label.name == 'ci:host-playground-e2e') || (github.event.action == 'synchronize' - && contains(github.event.pull_request.labels.*.name, 'host-playground-e2e'))) + && contains(github.event.pull_request.labels.*.name, 'ci:host-playground-e2e'))) uses: ./.github/workflows/host-playground-e2e.yml secrets: inherit permissions: diff --git a/.github/workflows/pr-triage.yml b/.github/workflows/pr-triage.yml new file mode 100644 index 0000000000..b188d955f0 --- /dev/null +++ b/.github/workflows/pr-triage.yml @@ -0,0 +1,118 @@ +name: Pull request triage + +# Gives every pull request the two labels a reviewer scans the list by, so +# nobody has to triage by hand when it goes up. docs/labels.md has the system. +# +# - `size:` from the lines changed, so a large pull request is visible as one +# before anyone opens it. +# - `status:waiting-on-review` on a pull request that is ready and says nothing +# else about where it stands. Drafts get no status until they are marked +# ready, and a draft loses this one if it goes back. +# +# pull_request_target, so a pull request from a fork can be labelled too. It +# never checks out the pull request's code: everything here reads the API. + +on: + pull_request_target: + types: [opened, reopened, synchronize, ready_for_review, converted_to_draft] + +permissions: + # contents to read .gitattributes from the base branch. + contents: read + pull-requests: write + issues: write + +concurrency: + group: pr-triage-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + triage: + name: Size and status + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { owner, repo } = context.repo; + const pr = context.payload.pull_request; + const number = pr.number; + const labels = pr.labels.map(l => l.name); + + const add = async names => names.length && github.rest.issues.addLabels({ + owner, repo, issue_number: number, labels: names, + }); + const remove = async name => github.rest.issues.removeLabel({ + owner, repo, issue_number: number, name, + }).catch(e => { if (e.status !== 404) throw e; }); + + // A backport is a vendored tree replaced wholesale, so its line + // count says nothing about how much there is to review. + const sizes = ['size:XS', 'size:S', 'size:M', 'size:L', 'size:XL', 'size:XXL']; + if (labels.includes('backport-host')) { + for (const s of labels.filter(l => sizes.includes(l))) await remove(s); + } else { + // Lines a reviewer does not read: whatever .gitattributes marks + // linguist-generated, which GitHub collapses in the diff too, read + // from the base branch so a pull request cannot shrink itself; + // plus lockfiles and the database schemas the build writes. + // As git reads a .gitattributes pattern: one with no slash matches + // at any depth, a leading slash anchors it to the root. + const glob = g => { + const anchored = g.includes('/'); + const body = g.replace(/^\//, '') + .replace(/[.+^${}()|[\]\\]/g, '\\$&') + .replace(/\*\*\//g, '\u0001') + .replace(/\*\*/g, '\0') + .replace(/\*/g, '[^/]*') + .replace(/\?/g, '[^/]') + .replace(/\u0001/g, '(.*/)?') + .replace(/\0/g, '.*'); + return new RegExp((anchored ? '^' : '(^|/)') + body + '$'); + }; + let generated = []; + try { + const { data } = await github.rest.repos.getContent({ + owner, repo, path: '.gitattributes', ref: pr.base.sha, + }); + generated = Buffer.from(data.content, 'base64').toString() + .split('\n') + .map(line => line.trim().split(/\s+/)) + .filter(([path, ...attrs]) => path && !path.startsWith('#') + && attrs.some(a => a === 'linguist-generated' || a === 'linguist-generated=true')) + .map(([path]) => glob(path)); + } catch (e) { + if (e.status !== 404) throw e; + } + const skipped = [ + ...generated, + /(^|\/)(Cargo\.lock|package-lock\.json|yarn\.lock|bun\.lockb|Package\.resolved)$/, + /(^|\/)database\/schemas\//, + /\.xcdatamodeld?\//, + ]; + const files = await github.paginate(github.rest.pulls.listFiles, { + owner, repo, pull_number: number, per_page: 100, + }); + const lines = files + .filter(f => !skipped.some(re => re.test(f.filename))) + .reduce((n, f) => n + f.additions + f.deletions, 0); + const size = lines < 10 ? 'size:XS' + : lines < 30 ? 'size:S' + : lines < 100 ? 'size:M' + : lines < 500 ? 'size:L' + : lines < 1000 ? 'size:XL' + : 'size:XXL'; + core.info(`${lines} reviewable lines: ${size}`); + for (const s of labels.filter(l => sizes.includes(l) && l !== size)) await remove(s); + if (!labels.includes(size)) await add([size]); + } + + // Decided from the pull request's state rather than the event, so a + // run cancelled by the next push leaves nothing the next run misses. + const waiting = 'status:waiting-on-review'; + if (pr.draft) { + if (labels.includes(waiting)) await remove(waiting); + } else if (!labels.some(l => l.startsWith('status:'))) { + await add([waiting]); + } diff --git a/.github/workflows/sync-labels.yml b/.github/workflows/sync-labels.yml new file mode 100644 index 0000000000..dc1aa9cbbb --- /dev/null +++ b/.github/workflows/sync-labels.yml @@ -0,0 +1,75 @@ +name: Sync labels + +# .github/labels.yml is the only place labels are defined. A pull request that +# changes it gets a dry run in its summary, so a reviewer sees exactly which +# labels it creates, renames, merges and deletes. The push to main applies it. +# +# Renames keep a label on everything that carries it, so a workflow that keys on +# a label name and the label itself change together when the pull request that +# renames both lands. + +on: + pull_request: + paths: + - ".github/labels.yml" + - "scripts/sync-labels.py" + - ".github/workflows/sync-labels.yml" + push: + branches: [main] + paths: + - ".github/labels.yml" + - "scripts/sync-labels.py" + - ".github/workflows/sync-labels.yml" + workflow_dispatch: + inputs: + apply: + description: "Apply the changes rather than only listing them" + type: boolean + default: false + +concurrency: + group: sync-labels-${{ github.ref }} + cancel-in-progress: false + +jobs: + # Read only, so a pull request's dry run can change nothing whatever the + # script on its branch says. + plan: + name: Plan label changes + if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && !inputs.apply) + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + # Without it the issues API leaves pull requests out of a label's count, + # and the plan can merge in the opposite direction from the apply. + issues: read + pull-requests: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: List what would change + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/sync-labels.py + + apply: + name: Apply label changes + if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.apply && github.ref == 'refs/heads/main') + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + # Labels live under the issues API, and merging one label into another + # relabels pull requests through it too. + issues: write + pull-requests: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Apply labels.yml + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/sync-labels.py --apply diff --git a/AGENTS.md b/AGENTS.md index f6c3bc92d6..52f036673c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -206,7 +206,7 @@ nightly-toolchain the dated nightly for rustfmt, CI clippy and rustdoc `ci-status`, which is the check worth requiring: a job skipped by its filter counts as a pass, so a gate cannot stall a PR it does not apply to. `Changeset guard` reads live PR titles and labels, so re-running failed jobs - picks up a `no-changeset` opt-out. `Release guard` rejects npm version changes + picks up a `ci:no-changeset` opt-out. `Release guard` rejects npm version changes with unconsumed changesets on the merge result, including in the merge queue. `registry-drift.yml` checks default-branch manifests against npm daily and maintains one issue; explicit package-version exceptions live in @@ -284,6 +284,15 @@ Two ways to lose work that involve no pushing at all: does not parse, and a `major` changeset whose title lacks `!`. The nightly announcements read `!` to list breaking changes first. +## Labels + +- Load `.claude/skills/labels/SKILL.md` before labelling a pull request or an + issue, and before adding or renaming a label. Pull requests get their size + and first status automatically and carry no area; add a `ci:` label only to + get the build it runs. Labels are defined in `.github/labels.yml`, so never + create one with `gh label` or the web UI. `docs/labels.md` describes the + system. + ## Scope of a change - Do not improve adjacent code, comments, or formatting unless asked. Do not diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de8bc637b7..c5127c0540 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Feature proposals live as markdown files in `docs/features/`. To propose a new f 2. Include YAML frontmatter (`title`, `type: feature`, `status: draft`, `author`, `pr`) 3. Describe the feature: summary, use cases, and proposed solution 4. Update `docs/features/_index.md` with a link to your file -5. Open a PR using the **feature** template (`?template=feature.md`) and add the `feature-request` and `proposal` labels +5. Open a PR using the **feature** template (`?template=feature.md`) ## RFCs @@ -21,7 +21,7 @@ For larger changes that need cross-team discussion, use the RFC process: 1. Create a branch and add a new file to `docs/rfcs/<slug>.md` (e.g., `docs/rfcs/my-proposal.md`) — do **not** assign a number 2. Use `docs/rfcs/0001-template.md` as a reference for the expected structure and frontmatter -3. Open a PR using the **rfc** template (`?template=rfc.md`) and add the `rfc` label +3. Open a PR using the **rfc** template (`?template=rfc.md`) 4. The PR will be auto-added to the project board for tracking and review 5. When the PR is approved and merged, CI automatically assigns the next sequential number, renames the file, and appends it to `docs/rfcs/_index.md` @@ -42,7 +42,11 @@ Canonical design documentation lives in `docs/design/`. To propose updates or ad 1. Edit or add a file in `docs/design/` 2. Include YAML frontmatter (`title`, `type: design`, `status`, `author`, `created`, `pr`) -3. Open a PR using the **design** template (`?template=design.md`) and add the `design-doc` label +3. Open a PR using the **design** template (`?template=design.md`) + +## Labels + +Pull requests get a size and a first status for you. The author or reviewer changes the `status:` when it stops waiting on review, add a `needs:` label when something blocks it, and a `ci:` label to ask for an app build. Issues take an `area:` and a `spa:`, and the area is filled in from the pull request that closes them. [docs/labels.md](docs/labels.md) has the whole system. ## Development diff --git a/README.md b/README.md index 824b2f77ac..bb6cb35cc7 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ TrUAPI (Triangle User-Agent Programming Interface) is the API surface that hosts - [TrUAPI reference](https://docs.polkadot.com/reference/apps/protocol/truapi/) - [Rust API reference](https://paritytech.github.io/trinity-user-agents/) +- [Labels](docs/labels.md) - [Building the apps for development](docs/local-app-builds.md) <!-- TODO: Add hero screenshot of the playground showing methods + a live call/response. Capture with a screenshot tool, save to `assets/screenshots/playground.png`, then place it here. --> @@ -581,15 +582,15 @@ and Dependabot runs get no secrets, and so does the merge queue. A push to main that touches those inputs runs the same suite through `ios-main.yml`, outside `CI Status`, and publishes the core pull requests reuse. `preview` is macOS time no check needs, so `on-label.yml` builds it once the pull request is -labelled `ios-simulator-build`. The same workflow's +labelled `ci:ios-simulator`. The same workflow's `TrUAPIHost package (Swift + WebKit)` job compiles the TrUAPIHost and TrUAPIProvider packages against the core the app jobs share, on a pull request touching their inputs, which the `swift` package in `.github/hosts.json` names, and runs their network permission tests. Like the rest of the iOS app it skips fork and Dependabot pull requests and the merge queue. The first time a pull request touches the iOS or Android app, `build-label-hint.yml` comments with -the labels that build it: `ios-simulator-build`, `ios-device-build` and -`android-device-build`. +the labels that build it: `ci:ios-simulator`, `ci:ios-device` and +`ci:android-device`. - `build`, a DevCI compile, failing on any build warning the committed baseline does not already have @@ -618,7 +619,7 @@ on the simulator, the emulator or a phone, without a deploy. See ### A build that installs on a phone -Label a pull request `ios-device-build` and `ios-device-preview.yml` produces a +Label a pull request `ci:ios-device` and `ios-device-preview.yml` produces a signed ad-hoc archive attached to the run, named for the commit it was built from. It uploads nowhere: not to Apple, not to any distribution service. @@ -634,7 +635,7 @@ preview itself is tracked on #681. ### An Android build that installs on a phone -Label a pull request `android-device-build` and `android-device-preview.yml` +Label a pull request `ci:android-device` and `android-device-preview.yml` attaches an installable APK to the run. Android needs no provisioning, so it installs on any phone rather than only on registered devices, and it is signed with the shared develop key so a new build replaces the last one rather than @@ -722,7 +723,7 @@ Remote Config, keyed on an `environment` signal the build sets. ### Instrumented tests `android-instrumented-tests.yml` boots an emulator and runs the app module's -connected tests. It starts from the `android-instrumented-tests` label rather +connected tests. It starts from the `ci:android-emulator-tests` label rather than from every commit, because the runner is macOS and a cold emulator costs minutes before the first assertion. `workflow_dispatch` runs it without a pull request to carry the label. diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md index 98247eb6b0..4025703ba8 100644 --- a/docs/RELEASE_PROCESS.md +++ b/docs/RELEASE_PROCESS.md @@ -28,14 +28,10 @@ and lockfiles, and package build scripts and configuration. Deleting, editing or renaming an existing changeset, or adding `.changeset/README.md`, does not satisfy the guard. -A change that ships nothing can use the `no-changeset` label. After adding the +A change that ships nothing can use the `ci:no-changeset` label. After adding the label or correcting a title to `release:`, select **Re-run failed jobs** on CI; the guard reads the current PR metadata, so no new commit or full CI run is -needed. Repository maintainers must create the label once before using it: - -```bash -gh label create no-changeset --color d4c5f9 --description "No published artifact changes; changeset not required" -``` +needed. The label is defined in `.github/labels.yml`, like every other. The first command writes a markdown file under `.changeset/`; the second consumes it, bumps the selected package `package.json`, appends the package diff --git a/docs/labels.md b/docs/labels.md new file mode 100644 index 0000000000..7b46cb7573 --- /dev/null +++ b/docs/labels.md @@ -0,0 +1,137 @@ +# Labels + +Labels answer what a reviewer or a planner asks before opening something: what does it touch, which product needs it, is anything blocking it, who acts next, and how big is it. Each family answers one of those questions, and its prefix says which. Names are `family:value`. + +Most labels are applied for you. On a pull request, the author or reviewer changes the `status:` when it stops waiting on review and adds a `needs:` label when something blocks it, and the author adds a `ci:` label to get an app built. On an issue, whoever files it sets the product, and the area is filled in when a pull request that closes it merges. + +Every label is defined in [`.github/labels.yml`](../.github/labels.yml). Change that file to add, rename or retire one; a pull request that does so lists exactly what it will change, and the merge applies it. + +## On issues + +| Family | Answers | Set by | +| --- | --- | --- | +| `area:` (core, ios, android, js, ci, docs, rfc) | What does it touch? | Automatically when a pull request that closes it merges, or by hand | +| `needs:` (decision, spec, UI) | What is blocking it? | Whoever works on it | +| `spa:` (humanity, jollity, scarcity, seity) | Which product needs it? | Whoever files it | + +An issue's type (Bug, Feature, Task), its status (Triage, Backlog, In progress), its priority and its target date are issue fields, not labels. + +## On pull requests + +| Family | Answers | Set by | +| --- | --- | --- | +| `status:` (waiting-on-review, waiting-on-author, ready-to-merge, blocked) | Who acts next? | `waiting-on-review` automatically, the rest by the author or reviewer | +| `needs:` (decision, spec, UI) | What is blocking it? | The author or reviewer | +| `size:` (XS to XXL) | How much is there to read? | Automatically, from the lines changed | +| `ci:` (ios-simulator, ios-device, android-device, android-emulator-tests, host-playground-e2e, no-changeset) | Which builds and checks run? | The author | + +A pull request usually carries a size and a status, and nothing else. + +## area + +[`.github/areas.yml`](../.github/areas.yml) maps paths to areas. When a pull request merges, `issue-areas.yml` adds the areas of the paths it changed to every issue it closes. Only closing references count: `Closes #12`, `Fixes #12`, or an issue linked under Development. A mention like "part of #12" does not, so an epic does not collect every area its pull requests touch, and a pull request that never merges labels nothing. Areas are only added, so one set by hand when the issue is filed stays. + +| Label | Paths | +| --- | --- | +| `area:core` | `rust/crates/` | +| `area:ios` | `hosts/ios/`, `ios/` | +| `area:android` | `hosts/android/`, `android/` | +| `area:js` | `js/`, `playground/`, `explorer/` | +| `area:ci` | `.github/workflows/`, `.github/actions/` | +| `area:docs` | `docs/` except `docs/rfcs/`, any `*.md` at the root | +| `area:rfc` | `docs/rfcs/` | + +An RFC is under `docs/` but is only `area:rfc`, so filtering on `area:docs` leaves RFCs out. + +The same paths decide who is asked to review in `.github/CODEOWNERS`, and `scripts/check-path-routing.py` keeps the two files in step. + +New pull requests carry no area, which keeps their labels to what a reviewer acts on. Older pull requests keep the areas they had. Giving pull requests areas is a change to `issue-areas.yml`, not to the labels. + +## needs + +What is blocking the work, on an issue or a pull request. + +| Label | Means | +| --- | --- | +| `needs:spec` | Accepted, but nothing is built or reviewed until a spec or design doc is agreed | +| `needs:decision` | Waiting on a decision, not on work | +| `needs:UI` | Cannot be built until the UI design exists | + +On a pull request, a `needs:` label says what it is waiting on. It does not affect CI. + +### When a pull request needs a spec + +Anyone reviewing a pull request can add `needs:spec` when the change makes a design decision nobody has agreed yet. Once it is on, nobody reviews the code: the conversation moves to the spec or design doc, and the label comes off when that merges. Which changes need a spec is decided with the design documentation work, and this section will link to it. + +## spa + +Which product an issue is for: `spa:humanity`, `spa:jollity`, `spa:scarcity` or `spa:seity`. Set by whoever files it. + +## status + +One at a time on a pull request, named for who has to act next. + +| Label | Means | +| --- | --- | +| `status:waiting-on-review` | Ready for a reviewer. Set automatically whenever a pull request that is not a draft has no status, and removed when it goes back to draft. | +| `status:waiting-on-author` | The author has changes to make. A reviewer sets it when they request changes. | +| `status:ready-to-merge` | Approved, and waiting only to be queued. | +| `status:blocked` | Cannot move until something else lands. Say what in a comment. | + +A draft carries no status, and converting a pull request back to draft removes `status:waiting-on-review`. + +## size + +Set on every pull request from the lines it adds and removes, and kept current as it changes. + +| Label | Lines | +| --- | --- | +| `size:XS` | under 10 | +| `size:S` | 10 to 29 | +| `size:M` | 30 to 99 | +| `size:L` | 100 to 499 | +| `size:XL` | 500 to 999 | +| `size:XXL` | 1000 or more | + +Lines a reviewer does not read are left out: anything `.gitattributes` marks `linguist-generated`, which GitHub also collapses in the diff, plus lockfiles, Room database schemas and Core Data models. Marking a new generated file there keeps it out of the count. A backport of a vendored host tree carries no size, because its line count says nothing about how much there is to review. + +`size:XL` and `size:XXL` are a prompt to split. A change too large to review in one sitting can usually land as a series of smaller pull requests into a feature branch, each reviewed by whoever knows that part, before the branch merges into main. When it genuinely cannot be split, say why in the description. + +## ci + +Each starts as soon as it is added and follows the branch from then on. The [README](../README.md#working-on-the-ios-host) covers the app builds in detail, and [docs/RELEASE_PROCESS.md](RELEASE_PROCESS.md) covers changesets. + +| Label | Runs | +| --- | --- | +| `ci:ios-simulator` | Builds the iOS app, runs its tests and attaches a simulator build | +| `ci:ios-device` | Attaches a signed iOS build for registered devices | +| `ci:android-device` | Attaches an Android APK for any phone | +| `ci:android-emulator-tests` | Runs the Android instrumented tests on an emulator | +| `ci:host-playground-e2e` | Runs the host-playground e2e inside both apps | +| `ci:no-changeset` | Lets the changeset check pass for a change that ships nothing | + +The first time a pull request touches an app, a comment lists `ci:ios-simulator`, `ci:ios-device` and `ci:android-device`, whichever build what it touches. + +## Outside the families + +A few labels are applied by automation that names them, so they keep plain names: `backport-host` on the pull requests `backport-host.yml` opens, `dependencies` on Dependabot's and `update-chain-specs.yml`'s, and `diagnosis-report`, which the playground puts on the issues it opens. + +## What is not a label + +- **An issue's type, status and target date.** Those are issue fields. +- **A breaking change.** A `!` in the pull request title marks it, and the nightly announcement lists those first. +- **Why an issue was closed.** GitHub records duplicates and issues not planned when the issue is closed. +- **Who reviews.** CODEOWNERS requests reviewers from the paths changed. + +## Changing a label + +Edit `.github/labels.yml`. Give every label a color, a description that says when to use it, a `target` and an `addedBy`. To rename one, put its old name under `previously`; the rename keeps it on everything that carries it. When the new name already exists, the old label is merged into it instead. A label that is no longer needed goes under `retired` with a reason, and is deleted when the change merges. One whose replacement is not decided yet goes under `pending`, and is left as it is. + +A workflow that keys on a label name changes in the same pull request as the label, so both land together. + +## Not yet decided + +- `Epic`: an issue type, or a feature with sub-issues. +- `enhancement`, `feature request` and `proposal`: replaced by the Feature issue type once issues move to types. +- `R2 blocker` and `R3+`: a target date, a field, or labels. +- `host-work`: an area for both hosts, or retired. diff --git a/docs/local-app-builds.md b/docs/local-app-builds.md index cea40ef908..619280a1b8 100644 --- a/docs/local-app-builds.md +++ b/docs/local-app-builds.md @@ -8,9 +8,9 @@ To request the dev credentials a local iOS build needs, reach out to the host SD | | Local | CI | |---|---|---| -| iOS simulator | Yes, with the dev credentials | `ios-simulator-build` label | -| iPhone | | `ios-device-build` label, once your device is registered | -| Android emulator or phone | | `android-device-build` label | +| iOS simulator | Yes, with the dev credentials | `ci:ios-simulator` label | +| iPhone | | `ci:ios-device` label, once your device is registered | +| Android emulator or phone | | `ci:android-device` label | | TestFlight, Firebase App Distribution, Play Store, GitHub releases | | Release workflows only | Every build here talks to the dev backend, so its accounts and backups land there. @@ -21,9 +21,9 @@ Add the label to your pull request. The run posts a comment on it with the downl | Label | Runs on | Delivers | Kept for | |---|---|---|---| -| `ios-simulator-build` | macOS | An arm64 simulator `.app`, for Apple Silicon Macs | 14 days | -| `ios-device-build` | macOS | A signed `.ipa` for registered devices | 14 days | -| `android-device-build` | Linux | An APK signed with the shared develop key | 5 days | +| `ci:ios-simulator` | macOS | An arm64 simulator `.app`, for Apple Silicon Macs | 14 days | +| `ci:ios-device` | macOS | A signed `.ipa` for registered devices | 14 days | +| `ci:android-device` | Linux | An APK signed with the shared develop key | 5 days | The Android build does not queue behind the macOS jobs. diff --git a/e2e/host-playground/README.md b/e2e/host-playground/README.md index d2680fb7c2..3090a5d65a 100644 --- a/e2e/host-playground/README.md +++ b/e2e/host-playground/README.md @@ -8,7 +8,7 @@ Runs the public `host-playground` product inside the iOS and Android host apps a - `release-notes.mjs`: adds a run's results to a nightly prerelease's notes. - `android/`, `ios/`: each platform's runner and the code added to its app for these builds only, so `hosts/` is never changed. -`.github/workflows/host-playground-e2e.yml` runs in three ways: from each nightly, on the commit it built, adding the results to that nightly's prerelease without ever failing the night; on a pull request labelled `host-playground-e2e`; and by dispatch. Each runner writes `results.json`, `report.md` and diagnostics for failures to `--out`, and exits non-zero when a test failed or the run stopped early. +`.github/workflows/host-playground-e2e.yml` runs in three ways: from each nightly, on the commit it built, adding the results to that nightly's prerelease without ever failing the night; on a pull request labelled `ci:host-playground-e2e`; and by dispatch. Each runner writes `results.json`, `report.md` and diagnostics for failures to `--out`, and exits non-zero when a test failed or the run stopped early. The test account must already hold an on-chain username on Paseo. Its mnemonic is read from a file and never printed. diff --git a/scripts/check-path-routing.py b/scripts/check-path-routing.py index 0f9081d626..a45b777229 100755 --- a/scripts/check-path-routing.py +++ b/scripts/check-path-routing.py @@ -1,14 +1,16 @@ #!/usr/bin/env python3 """Hold the labelling and the reviewer rules to the same set of paths. -`.github/labeler.yml` decides which labels a pull request gets, and -`.github/CODEOWNERS` decides who is asked to review it. Both answer the same +`.github/areas.yml` decides which area an issue gets from the pull request +that closes it, and `.github/CODEOWNERS` decides who is asked to review it. Both answer the same question, which paths belong to which area, and neither format can express the other, so they are two files. Two files drift. -This compares the roots each one names. A path that is labelled but owned by -nobody in particular, or owned but unlabelled, is reported. It does not compare -glob semantics, only that both files know about the same places. +This compares the roots each one names. A path that has an area but is owned +by nobody in particular, or owned but in no area, is reported. It does not compare +glob semantics, only that both files know about the same places. It also checks +that every area is a label `.github/labels.yml` defines, since issue-areas.yml +would otherwise create a misspelt one on GitHub. """ import pathlib @@ -18,10 +20,11 @@ import yaml ROOT = pathlib.Path(__file__).resolve().parent.parent -LABELER = ROOT / ".github" / "labeler.yml" +AREAS = ROOT / ".github" / "areas.yml" +LABELS = ROOT / ".github" / "labels.yml" CODEOWNERS = ROOT / ".github" / "CODEOWNERS" -# Areas the labeller describes by file suffix or by a directory that CODEOWNERS +# Areas described by file suffix or by a directory that CODEOWNERS # covers through a parent entry. Listing them keeps the check honest about what # it is choosing not to compare. EXEMPT = { @@ -36,18 +39,17 @@ def root_of(glob: str) -> str: return f"/{head}/" if head else "" -def labeller_roots() -> set[str]: - data = yaml.safe_load(LABELER.read_text()) +def area_roots() -> set[str]: + data = yaml.safe_load(AREAS.read_text()) roots = set() - for rules in data.values(): - for rule in rules: - for globs in rule.get("changed-files", []): - for glob in globs.get("any-glob-to-any-file", []): - if glob in EXEMPT: - continue - root = root_of(glob) - if root: - roots.add(root) + for globs in data.values(): + for glob in globs: + # An exclusion narrows an area inside a root it already names. + if glob in EXEMPT or glob.startswith("!"): + continue + root = root_of(glob) + if root: + roots.add(root) return roots @@ -64,24 +66,34 @@ def codeowner_roots() -> set[str]: return roots +def undefined_areas() -> list[str]: + defined = {label["name"] for label in yaml.safe_load(LABELS.read_text())["labels"]} + return sorted(set(yaml.safe_load(AREAS.read_text())) - defined) + + def main() -> int: - labelled = labeller_roots() + undefined = undefined_areas() + for area in undefined: + print(f"::error::{area} is an area in areas.yml but is not defined in labels.yml") + + labelled = area_roots() owned = codeowner_roots() unowned = sorted(labelled - owned) unlabelled = sorted(owned - labelled) for path in unowned: - print(f"::error::{path} is labelled but names no owner in CODEOWNERS") + print(f"::error::{path} has an area but names no owner in CODEOWNERS") for path in unlabelled: - print(f"::error::{path} names an owner but is not labelled in labeler.yml") + print(f"::error::{path} names an owner but has no area in areas.yml") if unowned or unlabelled: print("\nBoth files answer which paths belong to which area. " "Add the path to the other, or add it to EXEMPT here with a reason.") + if undefined or unowned or unlabelled: return 1 - print(f"labelling and ownership agree on {len(labelled)} paths") + print(f"areas and ownership agree on {len(labelled)} paths") return 0 diff --git a/scripts/lib/release-consistency.test.mjs b/scripts/lib/release-consistency.test.mjs index de0aba9062..8106b56c4d 100644 --- a/scripts/lib/release-consistency.test.mjs +++ b/scripts/lib/release-consistency.test.mjs @@ -204,7 +204,7 @@ test("a rerun reads changed PR metadata and does not use a stale opt-out", (t) = ); for (const [pr, status] of [ [{ title: "fix: behavior", labels: [] }, 1], - [{ title: "fix: behavior", labels: [{ name: "no-changeset" }] }, 0], + [{ title: "fix: behavior", labels: [{ name: "ci:no-changeset" }] }, 0], [{ title: "release: @parity/truapi 1.0.0", labels: [] }, 0], [{ title: "fix: behavior", labels: [] }, 1], ]) { diff --git a/scripts/sync-labels.py b/scripts/sync-labels.py new file mode 100755 index 0000000000..ff36fd988d --- /dev/null +++ b/scripts/sync-labels.py @@ -0,0 +1,247 @@ +#!/usr/bin/env python3 +"""Make the repository's labels match .github/labels.yml. + +Usage: + scripts/sync-labels.py [--apply] [--repo OWNER/NAME] + +Without --apply it only prints the plan. Reads and writes go through the `gh` +CLI, so GH_TOKEN or a logged-in `gh` decides what it may do. + +A label is renamed rather than recreated whenever one of its `previously` names +exists, because a rename keeps the label on every issue and pull request that +carries it. When the new name and an old one both exist, the one on fewer items +is merged into the other, and the survivor ends up with the new name: a merge +writes once per item, a rename once in total. Labels the file does not mention +are reported and left alone; only `retired` ones are deleted. + +Writes pause briefly and back off on GitHub's rate limits, and a merge skips +items that already carry the label, so a run cut short can be repeated. +""" + +import argparse +import json +import os +import pathlib +import re +import subprocess +import sys +import time +import urllib.parse + +import yaml + +ROOT = pathlib.Path(__file__).resolve().parent.parent +CONFIG = ROOT / ".github" / "labels.yml" +TARGETS = {"prs", "issues", "both"} +# GitHub's secondary rate limit allows about 80 writes a minute. +WRITE_PAUSE_SECS = 1.0 +RATE_LIMIT_RETRIES = 5 + + +def gh(*args: str, method: str = "GET", fields: dict | None = None) -> object: + cmd = ["gh", "api", "-X", method, *args] + for key, value in (fields or {}).items(): + if isinstance(value, list): + for item in value: + cmd += ["-f", f"{key}[]={item}"] + else: + cmd += ["-f", f"{key}={value}"] + for attempt in range(RATE_LIMIT_RETRIES + 1): + result = subprocess.run(cmd, capture_output=True, text=True) + if result.returncode == 0: + if method != "GET": + time.sleep(WRITE_PAUSE_SECS) + return json.loads(result.stdout) if result.stdout.strip() else None + limited = "rate limit" in result.stderr.lower() or "HTTP 429" in result.stderr + if not limited or attempt == RATE_LIMIT_RETRIES: + sys.stderr.write(result.stderr) + raise subprocess.CalledProcessError(result.returncode, cmd, result.stdout, result.stderr) + wait = 60 * (attempt + 1) + print(f"rate limited; retrying in {wait}s", file=sys.stderr) + time.sleep(wait) + raise AssertionError("unreachable") + + +def gh_paginate(path: str) -> list: + out = subprocess.run( + ["gh", "api", "--paginate", "--slurp", path], + check=True, capture_output=True, text=True, + ).stdout + return [item for page in json.loads(out) for item in page] + + +def quoted(name: str) -> str: + return urllib.parse.quote(name, safe="") + + +def load() -> dict: + data = yaml.safe_load(CONFIG.read_text()) + errors = [] + seen = {} + + def claim(name: str, where: str) -> None: + key = name.casefold() + if key in seen: + errors.append(f"{name!r} appears as {seen[key]} and as {where}") + seen[key] = where + + for label in data.get("labels", []): + name = label.get("name", "") + claim(name, "a label") + if not re.fullmatch(r"[0-9a-fA-F]{6}", str(label.get("color", ""))): + errors.append(f"{name!r} needs a six digit hex color") + if not label.get("description"): + errors.append(f"{name!r} needs a description") + elif len(label["description"]) > 100: + errors.append(f"{name!r} has a description over GitHub's 100 characters") + if label.get("target") not in TARGETS: + errors.append(f"{name!r} needs a target of prs, issues or both") + if not label.get("addedBy"): + errors.append(f"{name!r} needs an addedBy") + for old in label.get("previously", []): + claim(old, f"a previous name of {name!r}") + for section in ("retired", "pending"): + for entry in data.get(section, []): + claim(entry["name"], f"{section}") + if not entry.get("reason"): + errors.append(f"{entry['name']!r} in {section} needs a reason") + + if errors: + for error in errors: + print(f"::error file=.github/labels.yml::{error}") + sys.exit(1) + return data + + +def labelled(repo: str, name: str) -> list: + """Every issue and pull request carrying `name`, open or closed.""" + return gh_paginate(f"repos/{repo}/issues?state=all&per_page=100&labels={quoted(name)}") + + +def plan(data: dict, existing: dict, count) -> list[tuple]: + """Steps in the order they must run. Each is (kind, detail...). + + `count(name)` is how many items carry a label; it is asked only when a new + name and an old one both exist, to merge the smaller into the larger. + """ + steps = [] + remaining = dict(existing) # casefolded name -> label, as it will be + + for label in data["labels"]: + name, color, description = label["name"], label["color"].lower(), label["description"] + current = remaining.get(name.casefold()) + olds = [remaining[o.casefold()] for o in label.get("previously", []) if o.casefold() in remaining] + + if current is not None and olds: + sizes = {l["name"]: count(l["name"]) for l in [current, *olds]} + survivor = max([current, *olds], key=lambda l: sizes[l["name"]]) + if survivor is not current: + steps.append(("merge", current["name"], survivor["name"], sizes[current["name"]])) + remaining.pop(current["name"].casefold()) + olds.remove(survivor) + current = None + olds.insert(0, survivor) + for old in olds[1:] if current is None else []: + steps.append(("merge", old["name"], survivor["name"], sizes[old["name"]])) + remaining.pop(old["name"].casefold()) + if current is None: + olds = olds[:1] + else: + for old in olds: + steps.append(("merge", old["name"], name, sizes[old["name"]])) + remaining.pop(old["name"].casefold()) + olds = [] + + if current is None and olds: + first = olds.pop(0) + steps.append(("rename", first["name"], name, color, description)) + remaining.pop(first["name"].casefold()) + current = {"name": name, "color": color, "description": description} + remaining[name.casefold()] = current + elif current is None: + steps.append(("create", name, color, description)) + current = {"name": name, "color": color, "description": description} + remaining[name.casefold()] = current + elif (current["color"].lower(), current.get("description") or "") != (color, description) \ + or current["name"] != name: + steps.append(("update", current["name"], name, color, description)) + + for old in olds: + steps.append(("merge", old["name"], name, None)) + remaining.pop(old["name"].casefold()) + + for entry in data.get("retired", []): + if entry["name"].casefold() in remaining: + steps.append(("delete", remaining.pop(entry["name"].casefold())["name"], entry["reason"])) + + known = {l["name"].casefold() for l in data["labels"]} + known |= {e["name"].casefold() for e in data.get("pending", [])} + for key, label in sorted(remaining.items()): + if key not in known: + steps.append(("unmanaged", label["name"])) + return steps + + +def describe(step: tuple) -> str: + kind = step[0] + if kind == "create": + return f"create `{step[1]}`" + if kind == "rename": + return f"rename `{step[1]}` to `{step[2]}`, keeping it wherever it is applied" + if kind == "update": + return f"update `{step[2]}`'s color or description" + if kind == "merge": + items = "" if step[3] is None else f" ({step[3]} item{'s' if step[3] != 1 else ''})" + return f"move everything labelled `{step[1]}`{items} to `{step[2]}`, then delete `{step[1]}`" + if kind == "delete": + return f"delete `{step[1]}`: {step[2]}" + return f"leave `{step[1]}`: not in labels.yml" + + +def apply(repo: str, step: tuple) -> None: + kind = step[0] + if kind == "create": + gh(f"repos/{repo}/labels", method="POST", + fields={"name": step[1], "color": step[2], "description": step[3]}) + elif kind in ("rename", "update"): + gh(f"repos/{repo}/labels/{quoted(step[1])}", method="PATCH", + fields={"new_name": step[2], "color": step[3], "description": step[4]}) + elif kind == "merge": + old, new = step[1], step[2] + for item in labelled(repo, old): + if any(l["name"].casefold() == new.casefold() for l in item["labels"]): + continue + gh(f"repos/{repo}/issues/{item['number']}/labels", method="POST", fields={"labels": [new]}) + gh(f"repos/{repo}/labels/{quoted(old)}", method="DELETE") + elif kind == "delete": + gh(f"repos/{repo}/labels/{quoted(step[1])}", method="DELETE") + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--apply", action="store_true", help="make the changes rather than print them") + parser.add_argument("--repo", default=os.environ.get("GITHUB_REPOSITORY", "paritytech/trinity-user-agents")) + args = parser.parse_args() + + data = load() + existing = {l["name"].casefold(): l for l in gh_paginate(f"repos/{args.repo}/labels?per_page=100")} + steps = plan(data, existing, lambda name: len(labelled(args.repo, name))) + changes = [s for s in steps if s[0] != "unmanaged"] + + lines = [f"### Labels: {len(changes)} change{'s' if len(changes) != 1 else ''}", ""] + lines += [f"- {describe(s)}" for s in steps] or ["- nothing to do"] + report = "\n".join(lines) + print(report) + if summary := os.environ.get("GITHUB_STEP_SUMMARY"): + with open(summary, "a") as fh: + fh.write(report + "\n") + + if args.apply: + for step in changes: + apply(args.repo, step) + print(f"done: {describe(step)}") + return 0 + + +if __name__ == "__main__": + sys.exit(main())