From bee94b891deaaeeca31b0346da9d5b4b3a6fc01c Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 11:19:25 -0700 Subject: [PATCH 1/4] docs(rfc): add RFC 000.002 Flutter RFC Review & Decision Process Establish the review, socialization, and decision-making lifecycle for Flutter Requests for Comments (RFCs) to disentangle high-level architectural decision-making from code review across Flutter-owned repositories. Key elements established: - Self-contained threshold criteria distinguishing One-Pagers, Two-Pagers, and mandatory Full Design Docs / RFCs. - Clear roles for Author, Shepherd, Subsystem Tech Leads (TLs), the Flutter TLs group, and Flutter Leads. - 3-stage review lifecycle: Proposal & Draft PR (AAA.000), Socialization & The Dash Forum, and Asynchronous Approvals. - Optional Final Comment Period (FCP) for cooling off without stalling uncontroversial consensus. - Pre-merge sequential numbering constraint guaranteeing that AAA.000 never lands in main and rejected designs never burn sequential numbers. - Federated escalation path to the Flutter TLs group for deadlock resolution. Fixes: #3 --- rfc/000.002-flutter-rfc-review-process.md | 179 ++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 rfc/000.002-flutter-rfc-review-process.md diff --git a/rfc/000.002-flutter-rfc-review-process.md b/rfc/000.002-flutter-rfc-review-process.md new file mode 100644 index 0000000..2f0057b --- /dev/null +++ b/rfc/000.002-flutter-rfc-review-process.md @@ -0,0 +1,179 @@ +--- +type: rfc +rfc: '000.002' +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: + - codefu@google.com +--- + +# RFC 000.002: 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, 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 GitHub Discussions 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`). + +--- + +## 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 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.000-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) + Shepherd->>Repo: Submit primary Shepherd GitHub Approval + Author->>Repo: Assign sequential AAA.NNN & 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.NNN +``` + +### Stage 1: Proposal & Draft PR (`AAA.000`) +1. The author selects the primary 3-digit category `AAA` from [RFC 000.001: Flutter Architecture & Reference Taxonomy](000.001-flutter-architecture-and-reference-taxonomy.md). +2. The author opens a **Draft Pull Request** against `flutter/rfc`: + * File path: `rfc/AAA.000-kebab-case-title.md` + * Frontmatter: `rfc: 'AAA.000'`, `status: draft`, with secondary subsystems listed under `tags:`. + * The PR description **SHOULD** link to the underlying problem issue in `flutter/flutter` (e.g., `Fixes: flutter/flutter#...`). +3. **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. + +### 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.000` 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 and incorporate initial feedback from the Subsystem TLs overseeing the affected systems *before* booking a forum slot. Pre-alignment does not mean agreement. +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 or non-blocking suggestions **SHOULD NOT** delay FCP. + +#### Approvals + +1. **Required Approvals**: + * The proposal **MUST** receive a formal GitHub PR **Approve** from the Shepherd. + * The proposal **MUST** receive a formal GitHub PR **Approve** from at least one Subsystem TL representing each secondary subsystem listed under `tags:`. +2. **Sequential Number Allocation (Pre-Merge Requirement)**: + * **`AAA.000` 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.001](000.001-flutter-architecture-and-reference-taxonomy.md). + * The next available sequential index (`.001`, `.002`, ...) is determined. + * The author renames `rfc/AAA.000-title.md` to `rfc/AAA.NNN-title.md` and updates the frontmatter: + ```yaml + rfc: 'AAA.NNN' + status: stable + updated: YYYY-MM-DDTHH:MM:SSZ + ``` +3. **Merge**: The Shepherd merges the PR into `main`. Once merged, the RFC number `AAA.NNN` 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.000` cannot land in `main`, no permanent sequential `AAA.NNN` 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. From 593049fbffbafe1953c11462eb6e591c483a194f Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 11:24:05 -0700 Subject: [PATCH 2/4] white space --- rfc/000.002-flutter-rfc-review-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/000.002-flutter-rfc-review-process.md b/rfc/000.002-flutter-rfc-review-process.md index 2f0057b..4bdb1f0 100644 --- a/rfc/000.002-flutter-rfc-review-process.md +++ b/rfc/000.002-flutter-rfc-review-process.md @@ -129,7 +129,7 @@ For high-impact, cross-cutting, or contentious proposals requiring broad visibil ### Stage 3: Asynchronous Approvals -Approvals are recorded natively via GitHub PR Reviews. The PR conversation and git commit history serve as the authoritative record. +Approvals are recorded natively via GitHub PR Reviews. The PR conversation and git commit history serve as the authoritative record. #### Final Comment Period (OPTIONAL) From 5c8c49b9d332312e3c1e1fb22d9b5507436e0ae8 Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 16:24:10 -0700 Subject: [PATCH 3/4] no pocket veto --- rfc/000.002-flutter-rfc-review-process.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rfc/000.002-flutter-rfc-review-process.md b/rfc/000.002-flutter-rfc-review-process.md index 4bdb1f0..6fb1da5 100644 --- a/rfc/000.002-flutter-rfc-review-process.md +++ b/rfc/000.002-flutter-rfc-review-process.md @@ -96,7 +96,6 @@ sequenceDiagram Note over Repo: Objections submitted via PR "Request Changes" end SecTL->>Repo: Submit secondary Subsystem TL GitHub Approval(s) - Shepherd->>Repo: Submit primary Shepherd GitHub Approval Author->>Repo: Assign sequential AAA.NNN & update status: stable Shepherd->>Repo: Merge PR to main (Permanent immutable record) @@ -144,8 +143,8 @@ When discussion converges and open threads are addressed, the Shepherd **MAY** c #### Approvals 1. **Required Approvals**: - * The proposal **MUST** receive a formal GitHub PR **Approve** from the Shepherd. * 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.000` 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.001](000.001-flutter-architecture-and-reference-taxonomy.md). From 221c2b8e8d3c6ebacf1c310e9899084f2da150f8 Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 17:08:21 -0700 Subject: [PATCH 4/4] reviewer feedback --- ...=> 000.0002-flutter-rfc-review-process.md} | 55 +++++++++++-------- 1 file changed, 31 insertions(+), 24 deletions(-) rename rfc/{000.002-flutter-rfc-review-process.md => 000.0002-flutter-rfc-review-process.md} (76%) diff --git a/rfc/000.002-flutter-rfc-review-process.md b/rfc/000.0002-flutter-rfc-review-process.md similarity index 76% rename from rfc/000.002-flutter-rfc-review-process.md rename to rfc/000.0002-flutter-rfc-review-process.md index 6fb1da5..a68dad8 100644 --- a/rfc/000.002-flutter-rfc-review-process.md +++ b/rfc/000.0002-flutter-rfc-review-process.md @@ -1,6 +1,6 @@ --- type: rfc -rfc: '000.002' +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 @@ -9,10 +9,10 @@ updated: 2026-08-28T00:00:00Z tags: - 000-meta authors: - - codefu@google.com + - '"John McDole" ' --- -# RFC 000.002: Flutter RFC Review & Decision Process +# RFC 000.0002: Flutter RFC Review & Decision Process ## Overview @@ -36,12 +36,12 @@ The vast majority of engineering tasks in Flutter do **not** require an RFC. The | :--- | :--- | :--- | :--- | :---: | | **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, or governance. | Version-controlled Markdown in `flutter/rfc` | Formal RFC review, Dash Forum (consultative), Subsystem TL approval | **MUST** | +| **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 GitHub Discussions 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. +* **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: @@ -50,13 +50,14 @@ A proposal **MUST** go through the RFC process if it meets any of the following * **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 Final Comment Period (FCP). +* **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). @@ -78,7 +79,7 @@ sequenceDiagram participant Code as flutter/flutter (Code PR) Note over Author,Repo: Stage 1: Proposal & Draft PR - Author->>Repo: Open Draft PR: rfc/AAA.000-title.md (status: draft) + 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 @@ -96,23 +97,29 @@ sequenceDiagram Note over Repo: Objections submitted via PR "Request Changes" end SecTL->>Repo: Submit secondary Subsystem TL GitHub Approval(s) - Author->>Repo: Assign sequential AAA.NNN & update status: stable + 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.NNN + Author->>Code: Submit code PR referencing RFC-AAA.NNNN ``` -### Stage 1: Proposal & Draft PR (`AAA.000`) -1. The author selects the primary 3-digit category `AAA` from [RFC 000.001: Flutter Architecture & Reference Taxonomy](000.001-flutter-architecture-and-reference-taxonomy.md). +### 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.000-kebab-case-title.md` - * Frontmatter: `rfc: 'AAA.000'`, `status: draft`, with secondary subsystems listed under `tags:`. + * File path: `rfc/AAA.0000-kebab-case-title.md` + * Frontmatter: `rfc: 'AAA.0000'`, `status: draft`, author attribution (preferring GitHub profile URL `https://github.com/`, 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. **Shepherd Assignment & Triage**: +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. @@ -120,8 +127,8 @@ 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.000` 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 and incorporate initial feedback from the Subsystem TLs overseeing the affected systems *before* booking a forum slot. Pre-alignment does not mean agreement. +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. @@ -138,7 +145,7 @@ When discussion converges and open threads are addressed, the Shepherd **MAY** c > *"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 or non-blocking suggestions **SHOULD NOT** delay FCP. +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 @@ -146,16 +153,16 @@ When discussion converges and open threads are addressed, the Shepherd **MAY** c * 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.000` 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.001](000.001-flutter-architecture-and-reference-taxonomy.md). - * The next available sequential index (`.001`, `.002`, ...) is determined. - * The author renames `rfc/AAA.000-title.md` to `rfc/AAA.NNN-title.md` and updates the frontmatter: + * **`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.NNN' + 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.NNN` is permanent and immutable. +3. **Merge**: The Shepherd merges the PR into `main`. Once merged, the RFC number `AAA.NNNN` is permanent and immutable. --- @@ -165,7 +172,7 @@ To keep the repository's `main` branch clean and compliant with the Open Knowled * 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.000` cannot land in `main`, no permanent sequential `AAA.NNN` index is allocated, burned, or left as a gap in `main`.** +* **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. ---