docs(rfc): add RFC 000.0002 Flutter RFC Review & Decision Process by jtmcdole · Pull Request #4 · flutter/rfc

jtmcdole · 2026-08-28T18:23:04Z

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

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

jtmcdole · 2026-08-28T20:57:41Z

TODO: make sure to have wording around "no pocket vetos"

Piinks

Big fan.

Note to follow up on:

Current design doc page: https://github.com/flutter/flutter/blob/master/docs/contributing/Design-Documents.md
Current design doc template: flutter.dev/go/template
Breaking changes docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes
Mentions getting fcontrib accounts for design docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Contributor-access.md

Piinks · 2026-08-28T21:25:48Z

+* **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.


We could make flutter-tls a GitHub team that is taggable, assignable for reviews?

That sounds like a good idea.

Caveat: the members of this team would be visible.

But not their email - just their github account? That seems "fine" given you could figure that out from PRs, comments, and social media?

Piinks · 2026-08-28T21:36:00Z

+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)**:


I imagine folks will deviate from this in all sorts of ways. Any linting we could do?

I think we'll write a github action.

zanderso · 2026-08-28T22:34:24Z

+* **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:


Are there any changes to infrastructure or Flutter contributor workflows that would need an RFC?

Yes. E.g. external embedders would be a GREAT rfc.

zanderso · 2026-08-28T22:35:22Z

+* **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.


That sounds like a good idea.

jtmcdole · 2026-08-28T23:41:36Z

Big fan.

Note to follow up on:

Current design doc page: https://github.com/flutter/flutter/blob/master/docs/contributing/Design-Documents.md

Current design doc template: flutter.dev/go/template

Breaking changes docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes

Mentions getting fcontrib accounts for design docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Contributor-access.md

This is a non-blocking note right? As in "land this, and then we update all these other places"?

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

…pprovals

jtmcdole · 2026-08-31T23:49:10Z

Updated to latest requests. Note: this repo current has a requirement for 2-approvals before submitting.

zanderso · 2026-09-01T15:54:27Z

+
+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.


Can the Shepherd do a pocket veto? Should we include something to prevent that?

That's an escalation and falls under:

Flutter TLs Group: The collective body of Flutter Tech Leads (flutter-tls). Serves as the first-line escalation path for deadlocks.

The role-play here is:

a PR makes it through the review meeting and gets approvals from others

for some reason the shepherd drops the ball (no blame; I expect a shepherd that doesn't support a proposal to outright say no)

Anyone can request an escalation.

TLs review the case and handle accordingly.

There is probably room for attempted gamesmanship - I expect the TLs and Shepherd to act in the best interests of the project.

Piinks

LGTM

jtmcdole · 2026-09-11T17:41:52Z

Breaking changes docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#handling-breaking-changes

Mentions getting fcontrib accounts for design docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Contributor-access.md

FYI - I'm looking at these now.

jtmcdole mentioned this pull request Aug 28, 2026

docs(rfc): add RFC-000.0001 Flutter Architecture & Reference Taxonomy #1

Merged

jtmcdole requested review from Piinks and zanderso August 28, 2026 18:23

Piinks reviewed Aug 28, 2026

View reviewed changes

zanderso reviewed Aug 28, 2026

View reviewed changes

jtmcdole force-pushed the rfc000.002 branch from 13f8930 to 221c2b8 Compare August 29, 2026 00:08

jtmcdole requested review from Piinks and zanderso August 29, 2026 00:09

jtmcdole changed the title ~~docs(rfc): add RFC 000.002 Flutter RFC Review & Decision Process~~ docs(rfc): add RFC 000.0002 Flutter RFC Review & Decision Process Aug 29, 2026

jtmcdole added 4 commits August 31, 2026 15:12

white space

4c56c34

no pocket veto

3d390e5

reviewer feedback

a083fc6

jtmcdole force-pushed the rfc000.002 branch from 221c2b8 to a083fc6 Compare August 31, 2026 22:19

docs(rfc): replace Dash Forum with design review meeting and refine a…

1f1bbe9

…pprovals

zanderso reviewed Sep 1, 2026

View reviewed changes

zanderso approved these changes Sep 1, 2026

View reviewed changes

Piinks approved these changes Sep 2, 2026

View reviewed changes

stack merge was automatically disabled September 2, 2026 20:42
Pull Request is not mergeable

stack merge was automatically disabled September 2, 2026 20:43
Pull Request is not mergeable

jtmcdole merged commit 862b3c3 into main Sep 2, 2026
7 checks passed

jtmcdole added rfc-assigned AAA.NNN number assigned by the `rfc-assigned` action status: accepted labels Sep 11, 2026

jtmcdole deleted the rfc000.002 branch September 11, 2026 01:37

Uh oh!

Conversation

jtmcdole commented Aug 28, 2026

Uh oh!

jtmcdole commented Aug 28, 2026

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jtmcdole commented Aug 28, 2026

Uh oh!

jtmcdole commented Aug 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Piinks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jtmcdole commented Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants