docs(rfc): add RFC 000.0002 Flutter RFC Review & Decision Process

rfc/000.0002-flutter-rfc-review-process.md

@@ -0,0 +1,185 @@
+---
+type: rfc
+rfc: '000.0002'
+title: Flutter RFC Review & Decision Process
+description: Establishes the review lifecycle, threshold, shepherding, Dash Forum integration, and escalation rules for Flutter RFCs.
+status: draft
+created: 2026-08-28T00:00:00Z
+updated: 2026-08-28T00:00:00Z
+tags:
+  - 000-meta
+authors:
+  - '"John McDole" <codefu@google.com>'
+---
+
+# RFC 000.0002: Flutter RFC Review & Decision Process
+
+## Overview
+
+This document establishes the review, socialization, and decision-making lifecycle for Flutter Requests for Comments (RFCs).
+
+The primary goal of the Flutter RFC process is to **disentangle high-level architectural decision-making from code review**. Settling technical architecture, trade-offs, and subsystem boundaries before code is written ensures that subsequent code reviews on `flutter/flutter`, `flutter/packages`, `flutter/cocoon`, and other Flutter-owned repositories can focus strictly on implementation correctness, code quality, and testing rather than re-litigating design decisions.
+
+To maintain high development velocity and prevent bureaucratic stagnation, this process is engineered to be **lightweight, GitHub-native, and driven by federated Subsystem Tech Leads (TLs)** rather than a centralized council or committee.
+
+### Terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) ([RFC 2119](https://www.rfc-editor.org/info/rfc2119/)).
+
+---
+
+## When to Write an RFC (The Threshold)
+
+The vast majority of engineering tasks in Flutter do **not** require an RFC. The scope and complexity of an engineering initiative determines the appropriate level of design documentation:
+
+| Design Level | Scope & Complexity | Typical Artifact | Review & Approval Mechanism | Requires RFC? |
+| :--- | :--- | :--- | :--- | :---: |
+| **One-Pager** | Localized feature, bug fix, or refactor contained within a single subsystem. | GitHub Issue or clear PR description | Standard PR code review with Subsystem TL / peer review | **No** |
+| **Two-Pager** | Cross-subsystem feature consuming existing APIs in new ways without altering API/ABI contracts. | GitHub Discussion or lightweight design doc | Informal alignment between affected Subsystem TLs | **No** *(Optional)* |
+| **Full Design Doc (RFC)** | Architectural changes, cross-subsystem boundary shifts, new primitives, breaking changes, file formats, style guide, or governance. | Version-controlled Markdown in `flutter/rfc` | Formal RFC review, Dash Forum (consultative), Subsystem TL approval | **MUST** |
+
+### 1. Does NOT Require an RFC
+* **Bug fixes, performance optimizations, and internal refactors** that preserve existing API contracts and subsystem boundaries.
+* **One-Pagers**: Localized features or tasks contained within a single subsystem (Category `AAA`). These **SHOULD** be documented directly within a GitHub issue or a clear Pull Request description.
+* **Two-Pagers**: Projects with broader scope that consume other teams' APIs or subsystems in new ways without altering their public API/ABI contracts. These **SHOULD** be handled via Discord, GitHub Issues, or lightweight design docs with informal alignment between team TLs. Authors **MAY** optionally author these as lightweight RFCs if they seek broader community feedback, but a formal RFC is not required unless system boundaries or contracts change.
+
+### 2. MUST Require an RFC (Full Design Docs)
+A proposal **MUST** go through the RFC process if it meets any of the following criteria:
+* **Cross-Subsystem Architectural Impact**: Changes that cross or alter boundaries between major Flutter subsystems (e.g., Framework `100` $\leftrightarrow$ Engine `200`, Engine `200` $\leftrightarrow$ Embedders `400`).
+* **New Foundational Primitives**: Introducing new rendering backends, compilers, execution platforms, or embedder shells.
+* **File Formats & Protocols**: Specifying, altering, or deprecating file formats, data wire protocols, asset packaging schemes, or tooling interop protocols (e.g., tool daemon protocols, VM Service extensions).
+* **Breaking Changes & Deprecations**: Substantive alterations to public API/ABI contracts or project deprecation policies (Category `030`).
+* **Governance, Release, & Infrastructure Policies**: Changes to the RFC process, versioning, release cycles, or contributor standards (Category `000`–`020`).
+* **Style Changes**: Changes to the style guide.
+
+---
+
+## Roles & Responsibilities
+
+* **Author**: Proposes the design, creates the draft PR, drives discussion, and incorporates reviewer feedback. Anyone in the community **MAY** author an RFC.
+* **Shepherd**: A maintainer or Subsystem Tech Lead (TL) responsible for the primary taxonomy category `AAA`. The Shepherd ensures process momentum, validates category selection, tags secondary stakeholders, moderates discussion, and initiates the (optional) Final Comment Period (FCP).
+* **Subsystem Tech Leads (TLs)**: The technical leads overseeing the domains touched by the proposal.
+  * Flutter TLs **SHOULD** know about designs touching their systems.
+  * Formal sign-off requires approval from the primary Subsystem TL (or an appointed member) and affected secondary domain TLs (or their appointed members).
+* **Flutter TLs Group**: The collective body of Flutter Tech Leads (`flutter-tls`). Serves as the first-line escalation path for deadlocks.
+* **Flutter Leads**: The Flutter leadership team. Steps in to resolve disputes **only when requested** by the Flutter TLs group.
+
+---
+
+## The Review Lifecycle
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Author
+    participant Shepherd as Subsystem TL (Shepherd)
+    participant SecTL as Secondary Subsystem TL(s)
+    participant Forum as The Dash Forum (45 min)
+    participant Repo as flutter/rfc (GitHub PR)
+    participant Code as flutter/flutter (Code PR)
+
+    Note over Author,Repo: Stage 1: Proposal & Draft PR
+    Author->>Repo: Open Draft PR: rfc/AAA.0000-title.md (status: draft)
+    Shepherd->>Repo: Validate category AAA & confirm stakeholder tags
+
+    Note over Author,Forum: Stage 2: Socialization & Feedback
+    Author->>Repo: Async review via GitHub PR comments
+    opt Needs Broader Visibility / Contentious
+        Author->>Forum: Book 45-min Dash Forum slot (>=7 days lead time)
+        Shepherd->>Forum: Moderator Go/No-Go check (24h prior)
+        Forum->>Author: 45-min feedback & blindspots
+        Author->>Repo: Iterate text based on forum feedback
+    end
+
+    Note over Author,Repo: Stage 3: Asynchronous Approvals
+    opt [Optional] Final Comment Period (FCP)
+        Shepherd->>Repo: Announce FCP (7 calendar days, label: fcp-merge)
+        Note over Repo: Objections submitted via PR "Request Changes"
+    end
+    SecTL->>Repo: Submit secondary Subsystem TL GitHub Approval(s)
+    Author->>Repo: Assign sequential AAA.NNNN & update status: stable
+    Shepherd->>Repo: Merge PR to main (Permanent immutable record)
+
+    Note over Author,Code: Implementation
+    Author->>Code: Submit code PR referencing RFC-AAA.NNNN
+```
+
+### Stage 1: Proposal & Draft PR (`AAA.0000`)
+1. The author selects the primary 3-digit category `AAA` from [RFC 000.0001: Flutter Architecture & Reference Taxonomy](000.0001-flutter-architecture-and-reference-taxonomy.md).
+2. The author opens a **Draft Pull Request** against `flutter/rfc`:
+   * File path: `rfc/AAA.0000-kebab-case-title.md`
+   * Frontmatter: `rfc: 'AAA.0000'`, `status: draft`, author attribution (preferring GitHub profile URL `https://github.com/<username>`, e.g., `https://github.com/octocat`, or RFC 5322 mailbox format), and secondary subsystems listed under `tags:`.
+   * The PR description **SHOULD** link to the underlying problem issue in `flutter/flutter` (e.g., `Fixes: flutter/flutter#...`).
+3. **Link or File a Tracking Issue in `flutter/flutter`**:
+   * Link the RFC PR to an existing issue in `flutter/flutter`, or file a new [issue on flutter/flutter](https://github.com/flutter/flutter/issues) if one does not exist.
+   * Apply the `design doc` label to the issue. This notifies subscribers and enters the proposal into Flutter's issue triage queue.
+4. **Shepherd Assignment & Triage**:
+   * The Primary Subsystem TL for category `AAA` (or their designated delegate) acts as the RFC Shepherd.
+   * The Shepherd verifies that category `AAA` is appropriate and ensures that secondary subsystem TLs are tagged as reviewers/approvers on the PR.
+
+> [!NOTE]
+> Don't know who the Shepherd is for your RFC? One will be assigned during Flutter's issue triage.
+
+### Stage 2: Socialization & The Dash Forum
+
+Technical iteration occurs through GitHub PR line comments and reviews.
+
+For high-impact, cross-cutting, or contentious proposals requiring broad visibility, authors **SHOULD** present their proposal at **The Dash Forum**. The Dash Forum is a weekly 90-minute block divided into two 45-minute slots.
+
+#### Dash Forum Presentation Guidelines
+1. **Lead Time**: Authors **SHOULD** have an active `AAA.0000` Draft PR open on GitHub for at least **7 calendar days** prior to the scheduled forum date to ensure attendees have adequate review time.
+2. **Pre-Alignment**: Authors **MUST** pre-align with reviewers and incorporate initial feedback from the Subsystem TLs overseeing the affected systems *before* booking a forum slot. Pre-alignment does not mean agreement. It means questions that are answered are resolved and questions that remain are clear discussion topics.
+3. **Problem Issue Tagging**: Authors **SHOULD** apply the `design doc` label to the tracking issue in `flutter/flutter`. This alerts external contributors via Discord (`#hidden-chat`) and internal subscribers via the Dart GitHub label notifier.
+4. **Moderator Go/No-Go**: 24 hours prior to the forum, the assigned meeting moderator (typically the author's TL or the RFC Shepherd) reviews comment progress and makes a **Go/No-Go** decision. If substantive blockers are unresolved, the forum slot is postponed to avoid an unproductive session.
+5. **Feedback Only**: The Dash Forum is **explicitly intended for gathering feedback and surfacing architectural blindspots, NOT for making binding decisions**. Decisions are never made in the meeting; they are finalized asynchronously on the GitHub PR.
+
+### Stage 3: Asynchronous Approvals
+
+Approvals are recorded natively via GitHub PR Reviews. The PR conversation and git commit history serve as the authoritative record.
+
+#### Final Comment Period (OPTIONAL)
+
+When discussion converges and open threads are addressed, the Shepherd **MAY** choose to have a final comment period (FCP) for cooling off.
+
+1. The Shepherd posts a comment on the PR:
+   > *"I am proposing to move this RFC into Final Comment Period (FCP) with disposition: MERGE. FCP will close on [Date, 7 calendar days out]."*
+2. The Shepherd applies the GitHub label `fcp-merge`.
+3. FCP lasts for **7 calendar days**.
+4. Bikeshedding (spending an excessive amount of time on minor, trivial details while ignoring complex, important issues) or non-blocking suggestions **SHOULD NOT** delay FCP.
+
+#### Approvals
+
+1. **Required Approvals**:
+   * The proposal **MUST** receive a formal GitHub PR **Approve** from at least one Subsystem TL representing each secondary subsystem listed under `tags:`.
+   * **No Pocket Vetos**: Tagged reviewers **MUST** respond with an approval, a change request with technical rationale, or a designated alternate within **7 calendar days total** following the Dash Forum presentation (or within 7 calendar days of being tagged for review if forum presentation is not held). If no response is received within that time, the missing vote is overruled as an abstention, allowing the Shepherd to proceed without blocking the proposal.
+2. **Sequential Number Allocation (Pre-Merge Requirement)**:
+   * **`AAA.0000` cannot land in `main` and will not be used as a permanent RFC number.** The proposal **MUST** receive a sequential number before merging.
+   * Once all required approvals are submitted (and FCP concludes, if initiated), the author inspects merged files in `rfc/` under category `AAA` per the numbering rules in [RFC 000.0001](000.0001-flutter-architecture-and-reference-taxonomy.md).
+   * The next available sequential index (`.0001`, `.0002`, ...) is determined.
+   * The author renames `rfc/AAA.0000-title.md` to `rfc/AAA.NNNN-title.md` and updates the frontmatter:
+     ```yaml
+     rfc: 'AAA.NNNN'
+     status: stable
+     updated: YYYY-MM-DDTHH:MM:SSZ
+     ```
+3. **Merge**: The Shepherd merges the PR into `main`. Once merged, the RFC number `AAA.NNNN` is permanent and immutable.
+
+---
+
+## Rejections & Withdrawn Proposals
+
+To keep the repository's `main` branch clean and compliant with the Open Knowledge Format (OKF) schema:
+* If consensus cannot be reached, an unresolvable blocker emerges, or the author chooses not to proceed, the PR is **closed unmerged**.
+* The Shepherd posts a summary comment documenting the consensus findings and technical rationale for rejection.
+* The label `status: rejected` or `status: withdrawn` is applied to the closed PR.
+* **Because `AAA.0000` cannot land in `main`, no permanent sequential `AAA.NNNN` index is allocated, burned, or left as a gap in `main`.**
+* GitHub search permanently preserves the proposal, rationale, and discussion history on the closed PR for future reference.
+
+---
+
+## Escalation & Deadlock Resolution
+
+If the author, Shepherd, or affected Subsystem TLs reach an unresolvable impasse during review or FCP:
+
+1. **First-Line Escalation**: Disagreements **MUST** be escalated to the **Flutter TLs group** (`flutter-tls`). The TL group discusses the disagreement at their weekly sync to forge technical consensus.
+2. **Executive Escalation**: The **Flutter Leads** step in to break deadlocks **only when explicitly requested** by the Flutter TLs group.