Skip to content

Latest commit

 

History

History
193 lines (142 loc) · 13.9 KB

000.0002-flutter-rfc-review-process.md

File metadata and controls

193 lines (142 loc) · 13.9 KB
type rfc
rfc 000.0002
title Flutter RFC Review & Decision Process
description Establishes the review lifecycle, threshold, shepherding, design review meetings, and escalation rules for Flutter RFCs.
status draft
created 2026-08-28 00:00:00 UTC
updated 2026-08-28 00:00:00 UTC
tags
000-meta
authors
"John McDole" <[email protected]>

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 (RFC 2119).


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, design review meeting (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 Guide Changes: Changes to the Flutter style guide or project-wide formatting standards.

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, schedules design review meetings when needed, 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

sequenceDiagram
    autonumber
    actor Author
    participant Shepherd as Subsystem TL (Shepherd)
    participant SecTL as Secondary Subsystem TL(s)
    participant Review as Design Review (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,Review: Stage 2: Socialization & Feedback
    Author->>Repo: Async review via GitHub PR comments
    opt Needs Broader Visibility / Contentious
        Shepherd->>Review: Schedule 45-min Design Review (>=7 days lead time)
        Shepherd->>Review: Moderator Go/No-Go check (24h prior)
        Review->>Author: 45-min feedback & blindspots
        Author->>Repo: Iterate text based on review 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
Loading

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.
  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 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 & Design Review Meeting

Technical iteration occurs primarily through asynchronous GitHub PR line comments and reviews.

For high-impact, cross-cutting, or contentious proposals requiring broad visibility or synchronous architectural discussion, the proposal SHOULD be presented at an RFC Design Review meeting. The Shepherd is responsible for scheduling this 45-minute meeting on the appropriate calendar.

Design Review Meeting 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 meeting 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 the meeting is scheduled. 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 ensure the tracking issue in flutter/flutter has the design doc label applied. 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 meeting, the Shepherd (or assigned meeting moderator) reviews comment progress and makes a Go/No-Go decision. If substantive blockers are unresolved, the meeting is postponed to avoid an unproductive session.
  5. Feedback Only: The design review meeting 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 formal GitHub PR Approve reviews from the primary Subsystem TL (the Shepherd) and at least one Subsystem TL representing each secondary subsystem listed under tags:, ensuring that someone from each affected area reviews and approves.
    • 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 design review meeting (or within 7 calendar days of being tagged for review if no synchronous design review is 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.

    • 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:

      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.