From 7caf4697b26050813c4831040aca1637d0792fea Mon Sep 17 00:00:00 2001 From: John McDole Date: Thu, 27 Aug 2026 16:03:37 -0700 Subject: [PATCH 1/3] docs(rfc): add RFC-000.001 Flutter Architecture & Reference Taxonomy Establish the architecture taxonomy, numbering scheme, and lifecycle process for Flutter Requests for Comments (RFCs). - Introduce structured identifier format `RFC-AAA.NNN` across 8 core domains (000 Meta through 700 Documentation & Ecosystem). - Define file naming (`rfc/AAA.NNN-kebab-case.md`) and YAML frontmatter schema. - Outline a 4-step assignment lifecycle using `.000` draft placeholders to prevent number collisions during proposal phases. - Specify rules for cross-cutting proposals and number immutability. --- ...ter-architecture-and-reference-taxonomy.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 rfc/000.001-flutter-architecture-and-reference-taxonomy.md diff --git a/rfc/000.001-flutter-architecture-and-reference-taxonomy.md b/rfc/000.001-flutter-architecture-and-reference-taxonomy.md new file mode 100644 index 0000000..ff8d0ce --- /dev/null +++ b/rfc/000.001-flutter-architecture-and-reference-taxonomy.md @@ -0,0 +1,190 @@ +--- +rfc: RFC-000.001 +title: Flutter Architecture & Reference Taxonomy +status: draft (2026-08-27) +modification: 2026-08-27 +areas: + - 000-meta + - 600-infrastructure +author: codefu@google.com +--- + +# RFC 000.001: Flutter Architecture & Reference Taxonomy + +## Overview + +This document establishes the architecture taxonomy, identification scheme, and allocation process for Flutter Requests for Comments (RFCs). + +Every RFC in the Flutter project receives a structured identifier based on the primary architectural subsystem it affects, followed by a zero-padded sequential index: + +$$\text{RFC-AAA.NNN}$$ + +* **AAA (Category & Subcategory):** A three-digit classification representing the Flutter subsystem (e.g., `110` for Framework Foundation, `210` for Graphics Backends). +* **NNN (Sequential Index):** A three-digit zero-padded number (`001`–`999`) representing the proposal within that subcategory. + +--- + +## Architectural Taxonomy + +### 000 – General, Process, & Meta + +Governance and how the Flutter project itself functions. + +* **000:** RFC Process & Templates +* **010:** Governance & Steering Committees +* **020:** Release Cycles & Versioning Policy +* **030:** Breaking Change & Deprecation Policy + +### 100 – Flutter Framework Core + +The Dart-side architecture of Flutter. + +* **110:** Foundation & Low-level (e.g., Binding, Services, PlatformDispatcher) +* **120:** Rendering Layer (e.g., RenderObjects, Layout protocol, Painting) +* **130:** Widget Layer (e.g., Elements, BuildContext, Keys, State primitives) +* **140:** Gestures & Interaction (e.g., Pointer events, GestureArena) +* **150:** Animations & Physics (e.g., AnimationController, Curves, Simulations) +* **160:** Semantics & Accessibility (Framework) (e.g., SemanticsNode, Focus tree, Actions/Shortcuts) +* **170:** Text Editing & Selection (e.g., EditableText, TextSelection, Input formatters) + +### 200 – Flutter Engine & Graphics + +The C++ core and rendering subsystems. + +* **210:** Graphics Backends (e.g., Impeller, Skia, Metal, Vulkan, OpenGL) +* **220:** Layering & Compositing (e.g., SceneBuilder, Display Lists, Flow) +* **230:** Text & Typography (e.g., LibTxt, Paragraph styling, Font fallback) +* **240:** Input & Accessibility Core (Platform input events, OS accessibility bridge) +* **250:** Engine Runtime & Shell (e.g., Dart VM embedding, Isolate lifecycle, Asset resolution) + +### 300 – Design Systems & UI + +Visual components and user-facing design systems. + +* **310:** Material Design (e.g., M3 components, Theming) +* **320:** Cupertino (iOS) System +* **330:** Adaptive & Multi-platform UI +* **340:** Assets & Images (e.g., AssetBundle, Icon Fonts, Vector graphics) + +### 400 – Embedders & Platform Integration + +How Flutter integrates with host operating systems and runtimes. + +* **410:** Android Embedder +* **420:** iOS Embedder +* **430:** Web Embedder (e.g., CanvasKit, HTML, Wasm) +* **440:** Desktop Embedders (Windows, macOS, Linux) +* **450:** Plugins & Platform Channels (e.g., Pigeon, FFI / Native Assets) +* **460:** Custom & Embedded Systems (e.g., Automotive, Linux DRM/KMS, TV) + +### 500 – Developer Experience & Utilities + +The tools and environments developers use to build, test, and debug. + +* **510:** Flutter CLI (`flutter` tool) +* **520:** DevTools & Profiling +* **530:** Testing Frameworks (e.g., `flutter_test`, `integration_test`) +* **540:** IDE Plugins & Tooling Protocols (e.g., VS Code, IntelliJ, DDS, DAP, VM Service) + +### 600 – Infrastructure & EngProd + +The infrastructure that builds, tests, and validates Flutter and Dart SDKs. + +* **610:** CI/CD & LUCI Recipes +* **620:** Build Systems (e.g., GN/Ninja, CMake, Gradle) + +### 700 – Documentation & Ecosystem + +Community, documentation standards, and ecosystem packages. + +* **710:** API Documentation Standards & Style Guides +* **720:** pub.dev & Package Ecosystem +* **730:** Localization & Internationalization (i18n / l10n) +* **740:** Community, Outreach & Contributor Programs + +--- + +## RFC Identifier & File Naming Conventions + +### 1. Identifier Format + +Each RFC is uniquely identified by: + +$$\text{RFC-AAA.NNN}$$ + +* `AAA`: 3-digit subsystem category (e.g., `110`). +* `NNN`: 3-digit zero-padded index (e.g., `001`, `042`). +* Example: `RFC-110.042` + +### 2. File Path & Naming + +RFC files must be placed in the `rfc/` directory using lowercase kebab-case (slugified) format: + +$$\text{rfc/AAA.NNN-title.md}$$ + +* Example: `rfc/110.042-extract-value-notifier.md` +* Example: `rfc/000.001-flutter-architecture-and-reference-taxonomy.md` + +Using lowercase kebab-case prevents URL encoding issues (`%20`), simplifies shell automation, and ensures cross-platform filesystem consistency. Zero-padded numbers ensure proper lexicographical sorting. + +### 3. Frontmatter Metadata Standard + +Every RFC file must begin with YAML frontmatter conforming to this schema: + +```yaml +--- +rfc: RFC-110.042 +title: Extract Value Notifier +status: draft +created: 2026-08-27 +updated: 2026-08-27 +areas: + - 110-foundation +author: Jane Doe (@janedoe) +supersedes: RFC-110.012 # optional +superseded_by: RFC-110.050 # optional +--- +``` + +Valid statuses: `draft`, `in-review`, `accepted`, `rejected`, `implemented`, `superseded`. + +--- + +## RFC Number Assignment Process + +To prevent race conditions and merge conflicts when multiple proposals are submitted concurrently, numbers are assigned through the following lifecycle: + +```mermaid +flowchart LR + A["Draft Phase\n(rfc/AAA.000-title.md)"] --> B["Review & Triage\n(Shepherd validates category)"] + B --> C["Acceptance / FCP\n(Assign sequential .NNN)"] + C --> D["Merged & Permanent\n(Number never recycled)"] +``` + +### Step 1: Draft Proposal (Placeholder ID) +- An author selects the most applicable 3-digit category `AAA`. +- The author creates a PR using `.000` as the placeholder index: + - File: `rfc/AAA.000-my-proposal-title.md` + - Frontmatter: `rfc: RFC-AAA.000` and `status: draft` +- This ensures concurrent draft PRs in the same subcategory do not conflict on sequential numbers. + +### Step 2: Triage and Shepherd Review +- An assigned RFC Shepherd or maintainer verifies the category selection during initial review. +- If the proposal spans multiple areas, the shepherd helps identify the **primary** subsystem and ensures secondary areas are listed under `areas:` in frontmatter. + +### Step 3: Sequential Number Allocation +- When the RFC enters the **Final Comment Period (FCP)** or is approved for merge: + - The next available sequential number in subcategory `AAA` (`.001`, `.002`, ...) is determined by checking merged RFCs in `rfc/`. + - The author (or an automated GitHub Action) updates the frontmatter `rfc: RFC-AAA.NNN` and renames the file to `rfc/AAA.NNN-my-proposal-title.md`. + +### Step 4: Immutability and Number Retention +- Once assigned and merged, an RFC number is **permanent**. +- If an RFC is subsequently rejected, withdrawn, or superseded, the number is **never recycled** or reassigned, preserving persistent permalinks across Flutter documentation, issues, and code comments. + +--- + +## Cross-Cutting Proposals + +When a proposal spans multiple subsystems (e.g., Impeller graphics backend work requiring changes in the iOS embedder): +1. **Primary Category:** Assign the RFC number based on the subsystem where the primary architectural impact or implementation effort resides (e.g., `210` Graphics Backends). +2. **Secondary Tagging:** List all other affected subsystems in the `areas:` list of the YAML frontmatter (e.g., `areas: [210-graphics, 420-ios]`). From effb478a32c543d28361dd0b9b9e05ab762de978 Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 08:52:34 -0700 Subject: [PATCH 2/3] Address some comments and add OKF headers. --- ...ter-architecture-and-reference-taxonomy.md | 68 ++++++++++--------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/rfc/000.001-flutter-architecture-and-reference-taxonomy.md b/rfc/000.001-flutter-architecture-and-reference-taxonomy.md index ff8d0ce..d4d08af 100644 --- a/rfc/000.001-flutter-architecture-and-reference-taxonomy.md +++ b/rfc/000.001-flutter-architecture-and-reference-taxonomy.md @@ -1,12 +1,16 @@ --- -rfc: RFC-000.001 +type: rfc +rfc: '000.001' title: Flutter Architecture & Reference Taxonomy -status: draft (2026-08-27) -modification: 2026-08-27 -areas: +description: Establishes the architecture taxonomy, identification scheme, and allocation process for Flutter RFCs. +status: draft +created: 2026-08-27T00:00:00Z +updated: 2026-08-27T00:00:00Z +tags: - 000-meta - 600-infrastructure -author: codefu@google.com +authors: + - codefu@google.com --- # RFC 000.001: Flutter Architecture & Reference Taxonomy @@ -17,7 +21,7 @@ This document establishes the architecture taxonomy, identification scheme, and Every RFC in the Flutter project receives a structured identifier based on the primary architectural subsystem it affects, followed by a zero-padded sequential index: -$$\text{RFC-AAA.NNN}$$ +$$\text{AAA.NNN}$$ * **AAA (Category & Subcategory):** A three-digit classification representing the Flutter subsystem (e.g., `110` for Framework Foundation, `210` for Graphics Backends). * **NNN (Sequential Index):** A three-digit zero-padded number (`001`–`999`) representing the proposal within that subcategory. @@ -61,21 +65,19 @@ The C++ core and rendering subsystems. Visual components and user-facing design systems. -* **310:** Material Design (e.g., M3 components, Theming) -* **320:** Cupertino (iOS) System -* **330:** Adaptive & Multi-platform UI -* **340:** Assets & Images (e.g., AssetBundle, Icon Fonts, Vector graphics) +* **310:** Platform-Specific Design Systems +* **320:** Adaptive & Multi-platform UI +* **330:** Assets & Images (e.g., AssetBundle, Icon Fonts, Vector graphics) ### 400 – Embedders & Platform Integration How Flutter integrates with host operating systems and runtimes. -* **410:** Android Embedder -* **420:** iOS Embedder -* **430:** Web Embedder (e.g., CanvasKit, HTML, Wasm) -* **440:** Desktop Embedders (Windows, macOS, Linux) -* **450:** Plugins & Platform Channels (e.g., Pigeon, FFI / Native Assets) -* **460:** Custom & Embedded Systems (e.g., Automotive, Linux DRM/KMS, TV) +* **410:** Mobile Embedders +* **420:** Web Embedder (e.g., CanvasKit, HTML, Wasm) +* **430:** Desktop Embedders (Windows, macOS, Linux) +* **440:** Plugins & Platform Channels (e.g., Pigeon, FFI / Native Assets) +* **450:** Custom & Embedded Systems (e.g., Automotive, Linux DRM/KMS, TV) ### 500 – Developer Experience & Utilities @@ -110,11 +112,12 @@ Community, documentation standards, and ecosystem packages. Each RFC is uniquely identified by: -$$\text{RFC-AAA.NNN}$$ +$$\text{AAA.NNN}$$ * `AAA`: 3-digit subsystem category (e.g., `110`). * `NNN`: 3-digit zero-padded index (e.g., `001`, `042`). -* Example: `RFC-110.042` +* Example: `110.042` +* Example: `000.001` ### 2. File Path & Naming @@ -129,24 +132,27 @@ Using lowercase kebab-case prevents URL encoding issues (`%20`), simplifies shel ### 3. Frontmatter Metadata Standard -Every RFC file must begin with YAML frontmatter conforming to this schema: +Every RFC file must begin with YAML frontmatter conforming to this schema, aligned with the Open Knowledge Format (OKF) specification: ```yaml --- -rfc: RFC-110.042 +type: rfc +rfc: '110.042' title: Extract Value Notifier +description: Extract ValueNotifier and ChangeNotifier into a lightweight foundation package. status: draft -created: 2026-08-27 -updated: 2026-08-27 -areas: +created: 2026-08-27T00:00:00Z +updated: 2026-08-27T00:00:00Z +tags: - 110-foundation -author: Jane Doe (@janedoe) -supersedes: RFC-110.012 # optional -superseded_by: RFC-110.050 # optional +authors: + - Jane Doe (@janedoe) +supersedes: '110.012' # optional +superseded_by: '110.050' # optional --- ``` -Valid statuses: `draft`, `in-review`, `accepted`, `rejected`, `implemented`, `superseded`. +Valid statuses: `draft`, `stable`, `deprecated` (conforming to the Open Knowledge Format status lifecycle). Rejected proposals do not land in the codebase. Timestamps must be formatted as ISO 8601 UTC strings (`YYYY-MM-DDTHH:MM:SSZ`). --- @@ -165,17 +171,17 @@ flowchart LR - An author selects the most applicable 3-digit category `AAA`. - The author creates a PR using `.000` as the placeholder index: - File: `rfc/AAA.000-my-proposal-title.md` - - Frontmatter: `rfc: RFC-AAA.000` and `status: draft` + - Frontmatter: `rfc: 'AAA.000'` and `status: draft` - This ensures concurrent draft PRs in the same subcategory do not conflict on sequential numbers. ### Step 2: Triage and Shepherd Review - An assigned RFC Shepherd or maintainer verifies the category selection during initial review. -- If the proposal spans multiple areas, the shepherd helps identify the **primary** subsystem and ensures secondary areas are listed under `areas:` in frontmatter. +- If the proposal spans multiple areas, the shepherd helps identify the **primary** subsystem and ensures secondary areas are listed under `tags:` in frontmatter. ### Step 3: Sequential Number Allocation - When the RFC enters the **Final Comment Period (FCP)** or is approved for merge: - The next available sequential number in subcategory `AAA` (`.001`, `.002`, ...) is determined by checking merged RFCs in `rfc/`. - - The author (or an automated GitHub Action) updates the frontmatter `rfc: RFC-AAA.NNN` and renames the file to `rfc/AAA.NNN-my-proposal-title.md`. + - The author (or an automated GitHub Action) updates the frontmatter `rfc: 'AAA.NNN'` and renames the file to `rfc/AAA.NNN-my-proposal-title.md`. ### Step 4: Immutability and Number Retention - Once assigned and merged, an RFC number is **permanent**. @@ -187,4 +193,4 @@ flowchart LR When a proposal spans multiple subsystems (e.g., Impeller graphics backend work requiring changes in the iOS embedder): 1. **Primary Category:** Assign the RFC number based on the subsystem where the primary architectural impact or implementation effort resides (e.g., `210` Graphics Backends). -2. **Secondary Tagging:** List all other affected subsystems in the `areas:` list of the YAML frontmatter (e.g., `areas: [210-graphics, 420-ios]`). +2. **Secondary Tagging:** List all other affected subsystems in the `tags:` list of the YAML frontmatter (e.g., `tags: [210-graphics, 420-ios]`). From 8af26b7030c5326fe59d460eb80375c42a2253e4 Mon Sep 17 00:00:00 2001 From: John McDole Date: Fri, 28 Aug 2026 16:35:19 -0700 Subject: [PATCH 3/3] review: NNNN four-digit + prefer github attribution Leave optional mailbox format --- ...er-architecture-and-reference-taxonomy.md} | 52 +++++++++++-------- 1 file changed, 29 insertions(+), 23 deletions(-) rename rfc/{000.001-flutter-architecture-and-reference-taxonomy.md => 000.0001-flutter-architecture-and-reference-taxonomy.md} (79%) diff --git a/rfc/000.001-flutter-architecture-and-reference-taxonomy.md b/rfc/000.0001-flutter-architecture-and-reference-taxonomy.md similarity index 79% rename from rfc/000.001-flutter-architecture-and-reference-taxonomy.md rename to rfc/000.0001-flutter-architecture-and-reference-taxonomy.md index d4d08af..1f253e5 100644 --- a/rfc/000.001-flutter-architecture-and-reference-taxonomy.md +++ b/rfc/000.0001-flutter-architecture-and-reference-taxonomy.md @@ -1,6 +1,6 @@ --- type: rfc -rfc: '000.001' +rfc: '000.0001' title: Flutter Architecture & Reference Taxonomy description: Establishes the architecture taxonomy, identification scheme, and allocation process for Flutter RFCs. status: draft @@ -10,10 +10,10 @@ tags: - 000-meta - 600-infrastructure authors: - - codefu@google.com + - '"John McDole" ' --- -# RFC 000.001: Flutter Architecture & Reference Taxonomy +# RFC 000.0001: Flutter Architecture & Reference Taxonomy ## Overview @@ -21,10 +21,10 @@ This document establishes the architecture taxonomy, identification scheme, and Every RFC in the Flutter project receives a structured identifier based on the primary architectural subsystem it affects, followed by a zero-padded sequential index: -$$\text{AAA.NNN}$$ +$$\text{AAA.NNNN}$$ * **AAA (Category & Subcategory):** A three-digit classification representing the Flutter subsystem (e.g., `110` for Framework Foundation, `210` for Graphics Backends). -* **NNN (Sequential Index):** A three-digit zero-padded number (`001`–`999`) representing the proposal within that subcategory. +* **NNNN (Sequential Index):** A four-digit zero-padded number (`0001`–`9999`) representing the proposal within that subcategory. --- @@ -112,21 +112,21 @@ Community, documentation standards, and ecosystem packages. Each RFC is uniquely identified by: -$$\text{AAA.NNN}$$ +$$\text{AAA.NNNN}$$ * `AAA`: 3-digit subsystem category (e.g., `110`). -* `NNN`: 3-digit zero-padded index (e.g., `001`, `042`). -* Example: `110.042` -* Example: `000.001` +* `NNNN`: 4-digit zero-padded index (e.g., `0001`, `0042`). +* Example: `110.0042` +* Example: `000.0001` ### 2. File Path & Naming RFC files must be placed in the `rfc/` directory using lowercase kebab-case (slugified) format: -$$\text{rfc/AAA.NNN-title.md}$$ +$$\text{rfc/AAA.NNNN-title.md}$$ -* Example: `rfc/110.042-extract-value-notifier.md` -* Example: `rfc/000.001-flutter-architecture-and-reference-taxonomy.md` +* Example: `rfc/110.0042-extract-value-notifier.md` +* Example: `rfc/000.0001-flutter-architecture-and-reference-taxonomy.md` Using lowercase kebab-case prevents URL encoding issues (`%20`), simplifies shell automation, and ensures cross-platform filesystem consistency. Zero-padded numbers ensure proper lexicographical sorting. @@ -137,7 +137,7 @@ Every RFC file must begin with YAML frontmatter conforming to this schema, align ```yaml --- type: rfc -rfc: '110.042' +rfc: '110.0042' title: Extract Value Notifier description: Extract ValueNotifier and ChangeNotifier into a lightweight foundation package. status: draft @@ -146,14 +146,20 @@ updated: 2026-08-27T00:00:00Z tags: - 110-foundation authors: - - Jane Doe (@janedoe) -supersedes: '110.012' # optional -superseded_by: '110.050' # optional + - https://github.com/octocat +supersedes: '110.0012' # optional +superseded_by: '110.0050' # optional --- ``` Valid statuses: `draft`, `stable`, `deprecated` (conforming to the Open Knowledge Format status lifecycle). Rejected proposals do not land in the codebase. Timestamps must be formatted as ISO 8601 UTC strings (`YYYY-MM-DDTHH:MM:SSZ`). +#### Author Attribution Formats + +The `authors:` list supports two attribution formats: +1. **GitHub User Profile (Preferred):** Full URL to the author's GitHub profile (e.g., `https://github.com/octocat`). This is strongly preferred because it provides durable attribution linked directly to GitHub review activity, mentions, and issue tracking without exposing personal email addresses. +2. **RFC 5322 Mailbox Format:** Display name and email address formatted as `"Display Name" ` (e.g., `'"John McDole" '`). + --- ## RFC Number Assignment Process @@ -162,16 +168,16 @@ To prevent race conditions and merge conflicts when multiple proposals are submi ```mermaid flowchart LR - A["Draft Phase\n(rfc/AAA.000-title.md)"] --> B["Review & Triage\n(Shepherd validates category)"] - B --> C["Acceptance / FCP\n(Assign sequential .NNN)"] + A["Draft Phase\n(rfc/AAA.0000-title.md)"] --> B["Review & Triage\n(Shepherd validates category)"] + B --> C["Acceptance / FCP\n(Assign sequential .NNNN)"] C --> D["Merged & Permanent\n(Number never recycled)"] ``` ### Step 1: Draft Proposal (Placeholder ID) - An author selects the most applicable 3-digit category `AAA`. -- The author creates a PR using `.000` as the placeholder index: - - File: `rfc/AAA.000-my-proposal-title.md` - - Frontmatter: `rfc: 'AAA.000'` and `status: draft` +- The author creates a PR using `.0000` as the placeholder index: + - File: `rfc/AAA.0000-my-proposal-title.md` + - Frontmatter: `rfc: 'AAA.0000'` and `status: draft` - This ensures concurrent draft PRs in the same subcategory do not conflict on sequential numbers. ### Step 2: Triage and Shepherd Review @@ -180,8 +186,8 @@ flowchart LR ### Step 3: Sequential Number Allocation - When the RFC enters the **Final Comment Period (FCP)** or is approved for merge: - - The next available sequential number in subcategory `AAA` (`.001`, `.002`, ...) is determined by checking merged RFCs in `rfc/`. - - The author (or an automated GitHub Action) updates the frontmatter `rfc: 'AAA.NNN'` and renames the file to `rfc/AAA.NNN-my-proposal-title.md`. + - The next available sequential number in subcategory `AAA` (`.0001`, `.0002`, ...) is determined by checking merged RFCs in `rfc/`. + - The author (or an automated GitHub Action) updates the frontmatter `rfc: 'AAA.NNNN'` and renames the file to `rfc/AAA.NNNN-my-proposal-title.md`. ### Step 4: Immutability and Number Retention - Once assigned and merged, an RFC number is **permanent**.