commit	5809e1d5309c10e137f1c0a30939b8c8adac6739	[log] [tgz]
author	Lalit Maganti <lalitm@google.com>	Thu Jan 08 01:38:13 2026 +0000
committer	Lalit Maganti <lalitm@google.com>	Thu Jan 08 01:38:13 2026 +0000
tree	f9a2fa97cf9ac5b99039d2e261fb406ec5d932f5
parent	1199e9f3ff0ab946c6af9048509d8a8083832a6c [diff]

tree: f9a2fa97cf9ac5b99039d2e261fb406ec5d932f5

README.md

Perfetto RFCs

This repository is set up to automatically manage RFCs (Request for Comments) with GitHub Discussions integration.

TL;DR

Directly push changes to the rfcs branch without any review.
Any commit will trigger a creation/update of a matching entry in the GitHub Discussions page.
Hold the discussion in the GitHub Discussions entry.
Use GitHub permalink to quote inline snippets of the doc.

We are deliberately lax on the definition of RFC to keep the process lax and have a low-barrier process to both document and discuss design decisions of any size and controversy level.

📋 Overview

When you push or update an RFC markdown file, the system automatically:

📝 Creates/updates a corresponding GitHub Discussion
🔗 Links the discussion back to the source file
💬 Enables collaborative feedback through discussions

📝 Creating an RFC

File Naming Convention

RFC files must follow this naming pattern: <RFC_NUMBER>-<title-with-hyphens>.md

Examples:

0001-buffer.md
0002-ui-taskbar.md
0123-authentication-strategy.md

Important: The RFC number must be exactly 4 digits (zero-padded).

Directory Structure

repository-root/
├── 0001-buffer.md
├── 0002-ui-taskbar.md
├── media/
│   ├── 0001/
│   │   ├── buffer1.png
│   │   └── buffer2.svg
│   └── 0002/
│       └── ui-screenshot1.png
├── .github/
│   ├── workflows/
│   │   └── rfc-automation.yml
│   └── scripts/
│       └── sync_rfc_to_discussion.py
└── .markdownlint.json

Media Files

All images (SVG or PNG) should be placed in /media/<RFC_NUMBER>/:

✅ /media/0001/diagram.png
✅ /media/0001/architecture.svg
✅ /media/0002/screenshot.png
❌ /images/diagram.png (wrong location)
❌ /media/diagram.png (missing RFC number directory)

You are strongly encouraged to use draw.io / diagrams.net for your diagrams as it is able to embed metadata in both svg and png files, allowing for later re-editing.

If you use VSCode, you might find these two extensions particularly useful:

Draw.io integration particularly useful, as it allows to create diagrams directly within VSCode simply by creating a new empy xxx.drawio.{svg,png} file.
markdownlint

🚀 Workflow

Checkout/create the rfcs branch:
```
git checkout -b rfcs -t origin/rfcs
```
Create your RFC:: Copy the rfc-template.md
Add content: Edit your RFC file with your markdown content. Include:
- Problem statement
- Proposed solution
- Alternatives considered
- Implementation details
- References to media files if needed

Add media files (optional):

mkdir -p media/0001
touch media/0001/diagram.drawio.png
# Edit with vscode or app.diagrams.net

Commit and push:

git add 0001-buffer.md media/0001/
git commit -m "Add RFC-0001: Buffer Management"
git push

Automated actions:
- Markdown linter runs automatically
- GitHub Discussion is created/updated
- Team can comment and provide feedback

💬 GitHub Discussions

Each RFC automatically gets a GitHub Discussion created in the repository. The discussion:

Contains the full RFC content
Links back to the source file
Updates when the RFC file is modified
Serves as the central place for team feedback