feat(review): route PRs by areas and topics and manage rosters through reviewed PRs #4839

User Story

As an OpenShell maintainer, I coordinate reviews and maintain the project's maintainer-approval check. I need PRs to reach people who understand the affected components and technical concerns. I also need contributors to be able to volunteer for that work through a public, reviewed change.

Problem Statement

OpenShell has agreed on a proposed set of areas and topics, but the repository does not yet provide a canonical registry connecting those categories to maintainers, reviewers, and subscribers. Selecting the right reviewers depends on individual knowledge and manual requests. There is no consistent, reviewed way to join or leave an area or topic.

Impact / Why This Matters

Relevant specialists can miss changes, authors have to discover who to ask, and review load can concentrate on a few maintainers. Existing maintainer approval establishes project authorization but does not by itself route a PR to the right subject-matter experts.

Proposed Design

• Add a human-readable, machine-consumable REVIEWERS.md, with a section for each area and topic, its scope, and its membership. Use the reviewed taxonomy as the starting point.
• Bootstrap the registry with suggested people in an initial PR. Invite community review to add, remove, or correct those suggestions before treating them as confirmed participation.
• Make a reviewed PR to REVIEWERS.md the sign-up mechanism for everyone, including changes of scope, role, and withdrawal. Subscriber entries require the person's own opt-in; suggested initial names do not establish consent.
• Distinguish maintainer, reviewer, and subscriber participation using repository privileges. The registry records category membership; it does not grant repository privileges. Reconciling today's permissions and the future CNCF organization's permission model is outside this issue's scope.
• Aim for at least two confirmed maintainers covering each area and topic. Make gaps visible during bootstrap rather than presenting proposed names as established coverage.
• Give every ready-for-review PR exactly one primary area for review coordination. Allow zero or more relevant topics, without an arbitrary hard cap. Cross-area impact must still bring in the affected expertise.
• Automatically select relevant non-author reviewers from the area/topic rosters when a PR is ready for review. Reuse people who cover several categories, distribute requests among eligible volunteers, and support human correction or reassignment.
• Let subscribers follow matching PRs without taking on a review obligation. Deduplicate notifications across matching categories and avoid repeated notifications on unchanged classification. People without write access can participate as subscribers and contribute feedback.

Review routing and subscription delivery are proposed behavior. Keep the existing maintainer approval requirement intact; selecting a reviewer does not itself introduce a new merge gate or require every member of a roster to approve.

Suggested UX

1. A contributor opens a PR adding their handle to topic:policy in REVIEWERS.md, with their intended role and any scope limitations. The membership change takes effect after review and merge.
2. A PR affecting runtime policy is classified with area:runtime and topic:policy. When ready, it receives an area-maintainer review request and the relevant policy review request, deduplicated when the same person covers both.
3. Opted-in subscribers receive a matching-work notification. An author or maintainer can correct classification and replace an unavailable reviewer without restarting the entire process.

Acceptance Criteria

• The repository has a Markdown registry defining all agreed areas/topics and their membership, with a documented format tools can consume.
• People join, change, or leave category membership through a reviewed PR; suggested and confirmed participation are distinguishable during bootstrap.
• Role eligibility follows repository privileges without introducing a second permission-granting system or changing organization permissions.
• Coverage gaps, including categories with fewer than two confirmed maintainers, are visible.
• Ready PRs have one primary area; relevant topics and secondary-area impact inform review routing.
• Relevant eligible non-author reviewers are selected automatically, requests are deduplicated, and human reassignment is supported.
• Opted-in subscribers can follow areas/topics regardless of write access, with a documented delivery and unsubscribe behavior.
• Registry/classification validation catches unknown categories, invalid membership records, and duplicates.
• Routing uses trusted merged membership; a PR cannot enroll itself as an authorized reviewer by editing its own proposed registry.
• Existing maintainer approval and protected review machinery continue to apply.

Alternatives Considered

• CODEOWNERS alone: useful for paths and existing protected machinery, but insufficient for semantic topics or subscriber participation.
• A spreadsheet as the permanent registry: easy to collect names, but separates review routing from versioned, reviewed repository data. Use a PR for sign-up instead.
• GitHub teams as the canonical registry: potentially useful as an integration later, but permission alignment and organization migration should not block the initial registry.
• Request everyone on each matching roster: increases notification load and dilutes responsibility. Select relevant reviewers and notify subscribers separately.

Implementation Sequence

Start with a registry proposal PR for community review, then implement routing and subscriptions against the agreed format. If these are separate PRs, create scoped implementation issues so each PR can close an issue covering its own work. This issue tracks the overall outcome.