Skip to content

Commit c2bd82c

Browse files
benbrandtbenbrandt
committed
Introduce rfd process
1 parent bca6709 commit c2bd82c

5 files changed

Lines changed: 268 additions & 32 deletions

File tree

‎docs/docs.json‎

Lines changed: 43 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -41,46 +41,58 @@
4141
]
4242
},
4343
"navigation": {
44-
"groups": [
44+
"tabs": [
4545
{
46-
"group": "Overview",
46+
"tab": "Protocol",
4747
"pages": [
48-
"overview/introduction",
49-
"overview/architecture",
50-
"overview/agents",
51-
"overview/clients"
48+
{
49+
"group": "Overview",
50+
"pages": [
51+
"overview/introduction",
52+
"overview/architecture",
53+
"overview/agents",
54+
"overview/clients"
55+
]
56+
},
57+
{
58+
"group": "Protocol",
59+
"pages": [
60+
"protocol/overview",
61+
"protocol/initialization",
62+
"protocol/session-setup",
63+
"protocol/prompt-turn",
64+
"protocol/content",
65+
"protocol/tool-calls",
66+
"protocol/file-system",
67+
"protocol/terminals",
68+
"protocol/agent-plan",
69+
"protocol/session-modes",
70+
"protocol/slash-commands",
71+
"protocol/extensibility",
72+
"protocol/transports",
73+
"protocol/schema"
74+
]
75+
},
76+
{
77+
"group": "Libraries",
78+
"pages": [
79+
"libraries/kotlin",
80+
"libraries/rust",
81+
"libraries/typescript",
82+
"libraries/community"
83+
]
84+
}
5285
]
5386
},
5487
{
55-
"group": "Protocol",
88+
"tab": "RFDs",
5689
"pages": [
57-
"protocol/overview",
58-
"protocol/initialization",
59-
"protocol/session-setup",
60-
"protocol/prompt-turn",
61-
"protocol/content",
62-
"protocol/tool-calls",
63-
"protocol/file-system",
64-
"protocol/terminals",
65-
"protocol/agent-plan",
66-
"protocol/session-modes",
67-
"protocol/slash-commands",
68-
"protocol/extensibility",
69-
"protocol/transports",
70-
"protocol/schema"
90+
"rfds/about",
91+
{ "group": "Draft", "pages": ["rfds/introduce-rfd-process"] }
7192
]
7293
},
7394
{
74-
"group": "Libraries",
75-
"pages": [
76-
"libraries/kotlin",
77-
"libraries/rust",
78-
"libraries/typescript",
79-
"libraries/community"
80-
]
81-
},
82-
{
83-
"group": "Community",
95+
"tab": "Community",
8496
"pages": [
8597
"community/governance",
8698
"community/code-of-conduct",

‎docs/rfds/TEMPLATE.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<!--
2+
3+
Instructions:
4+
5+
* Copy this file and give it a name like my-feature-slug.mdx
6+
* Do not remove the `>` sections -- they are part of the template!
7+
* Replace the HTML comments that give general guidance with your answers and content. Do not begin your answers with `>`, your text should be unquoted.
8+
* For optional sections, you can leave the HTML comment as is if you do not wish to provide an answer.
9+
* In the FAQ, begin each question with a markdown `##` section so that it gets a linkable anchor.
10+
11+
-->
12+
13+
---
14+
15+
## title: "RFD TITLE"
16+
17+
# Elevator pitch
18+
19+
> What are you proposing to change?
20+
21+
<!--
22+
Give a brief, high-level overview of what you plan to do and what problem you are solving. Feel free to use bullet points to help clarify the structure.
23+
-->
24+
25+
# Status quo
26+
27+
> How do things work today and what problems does this cause? Why would we change things?
28+
29+
# What we propose to do about it
30+
31+
> What are you proposing to improve the situation?
32+
33+
<!--
34+
Use this section to describe what you propose to do at a high-level.
35+
Don't give every detail, this should be the high-level summary.
36+
37+
Note: This section is OPTIONAL when RFDs are first opened.
38+
You can also include multiple variants if you have different ideas of how to approach the problem, though these should be narrowed down as the RFD progresses.
39+
-->
40+
41+
# Shiny future
42+
43+
> How will things will play out once this feature exists?
44+
45+
<!--
46+
Use this section to describe the "status quo" as it will play out once
47+
we have made these changes.
48+
49+
Note: This section is OPTIONAL when RFDs are first opened.
50+
-->
51+
52+
# Implementation details and plan
53+
54+
> Tell me more about your implementation. What is your detailed implementaton plan?
55+
56+
<!--
57+
Use this section to add details that were not covered in the "What we propose to do about it" section and also include an implementation plan with phases.
58+
59+
Note: This section is OPTIONAL and NOT RECOMMENDED when RFDs are first opened. It can distract from the discussion of the problem.
60+
-->
61+
62+
# Frequently asked questions
63+
64+
> What questions have arisen over the course of authoring this document or during subsequent discussions?
65+
66+
<!--
67+
Keep this section up-to-date as discussion proceeds. The goal is to capture major points that came up on a PR or in a discussion forum -- and if they reoccur, to point people to the FAQ so that we can start the dialog from a more informed place.
68+
-->
69+
70+
## What alternative approaches did you consider, and why did you settle on this one?
71+
72+
None. The idea came to me fully formed, like Athena springing from Zeus's head.
73+
74+
<!-- You...may want to adjust this. -->
75+
76+
# Revision history
77+
78+
<!-- If there have been major updates to this RFD, you can include the git revisions and a summary of the changes. -->

‎docs/rfds/about.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: "Requests for Dialog (RFDs)"
3+
description: "Our process for introducing changes to the protocol"
4+
---
5+
6+
A "Request for Dialog" (RFD) is ACP's version of the RFC process. RFDs are the primary mechanism for proposing new features, collecting community input on an issue, and documenting design decisions.
7+
8+
## When to write an RFD
9+
10+
You should consider writing an RFD if you intend to make a "substantial" change to ACP or its documentation. What constitutes a "substantial" change is evolving based on community norms and varies depending on what part of the ecosystem you are proposing to change.
11+
12+
Some changes do not require an RFD:
13+
14+
- Rephrasing, reorganizing or refactoring
15+
- Addition or removal of warnings
16+
- Additions that strictly improve objective, numerical quality criteria (speedup, better browser support)
17+
- Fixing objectively incorrect behavior
18+
19+
## The RFD Process
20+
21+
### 1. Propose by opening a PR
22+
23+
Fork the repo and copy `rfds/TEMPLATE.md` to `rfds/my-feature.md` (using kebab-case naming). The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration.
24+
25+
### 2. Merge to "Draft" when championed
26+
27+
RFD proposals are merged into the "Draft" section if a core team member decides to champion them. The champion becomes the point-of-contact and will work with authors to make it reality. Once in draft, implementation may begin (properly feature-gated with the RFD name). Implementation can also begin at a particular SDK or agent/client level to prove out the design for better review and feedback before broader adoption.
28+
29+
RFDs are living documents that track implementation progress. PRs working towards an RFC will typically update it to reflect changes in design or direction.
30+
31+
### 2b. Move to "To be removed"
32+
33+
RFDs that have never landed may be closed at the discretion of a core team member. RFDs that have landed in draft form are moved to "To be removed" instead until there has been time to remove them fully from the codebase, then they are removed entirely.
34+
35+
### 3. Move to "Preview" when fully implemented
36+
37+
When the champion feels the RFD is ready for broader review, they open a PR to move it to "Preview." This signals the community to provide feedback. The PR stays open for a few days before the champion decides whether to land it.
38+
39+
### 4. Completed
40+
41+
Once in preview, the RFD can be moved to "completed" with a final PR. The core team should comment and express concerns, but **final decision is always made by the core team lead**. Depending on what the RFD is about, "completed" is the only state that can represent a 1-way door (if there is a stability commitment involved), as changes might require a breaking change to the protocol after this point.
42+
43+
Preview RFDs don't have to be completed. They may also go back to draft to await further changes or even be moved ot "To be removed".
44+
45+
### 5. Implementation and completion
46+
47+
#### RFD Lifecycle
48+
49+
- **Early drafts**: Initial ideas, brainstorming, early exploration
50+
- **Mature drafts**: Well-formed proposals ready for broader review
51+
- **Accepted**: Approved for implementation, may reference implementation work
52+
- **To be removed (yet?)**: Decided against for now, but preserved for future consideration
53+
- **Completed**: Implementation finished and merged
54+
55+
## Governance
56+
57+
The project currently has a design team with the [Zed team as the lead (BDFL)](../community/governance). Champions from the core team guide RFDs through the process, but final decisions rest with the team lead. This structure maintains velocity while anticipating future governance expansion.
58+
59+
## Discussion and Moderation
60+
61+
Detailed discussions often happen on Slack, with PR comments for process decisions. The results of detailed discussions should be incorporated into the relevant RFD. RFD champions actively curate discussions by collecting questions in the FAQ section. If PR discussions become too long, they should be closed, feedback summarized, and reopened with links to the original.
62+
63+
## Licensing
64+
65+
All RFDs are licensed under Apache 2.0. The project remains open source.
66+
67+
##

‎docs/rfds/introduce-rfd-process.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: "Introduce RFD Process"
3+
---
4+
5+
# Elevator pitch
6+
7+
> What are you proposing to change? Bullet points welcome.
8+
9+
Introduce a "Request for Dialog" (RFD) process to replace ad-hoc design discussions with structured, community-friendly design documents that track features from conception to completion.
10+
11+
# Status quo
12+
13+
> How do things work today and what problems does this cause? Why would we change things?
14+
15+
Currently all development is being done primarily by the Zed team tracking requests and proposals from multiple teams. The goal is to create a process that helps to keep files organized and which can scale to participation by an emerging community.
16+
17+
# Shiny future
18+
19+
> How will things will play out once this feature exists?
20+
21+
## Project licensing
22+
23+
All code and RFDs are licensed under an Apache 2.0 license. The project is intended to remain open source and freely available in perpetuity.
24+
25+
## Decision making
26+
27+
For the initial phase, the project shall have a "design team" that consists of the Zed team acting in "BDFL" capacity. The expectation is that the project will setup a more structure governance structure as it grows. The design team makes all decisions regarding RFDs and sets overall project direction.
28+
29+
## RFD lifecycle
30+
31+
### RFDs are proposed by opening a PR
32+
33+
An RFD begins as a PR adding a new file into the "Draft" section. The RFD can start minimal - just an elevator pitch and status quo are enough to begin dialog. Pull requests become the discussion forum where ideas get refined through collaborative iteration.
34+
35+
As discussion proceeds, the FAQ of the RFD should be extended. If discussion has been going long enough, the PR should be closed, feedback summarized, and then re-opened with a link to the original PR.
36+
37+
### The PR is merged into "draft" once a core team member decides to champion it
38+
39+
RFD proposals are merged into the "draft" section if a core team member decides to champion them. The champion is then the point-of-contact for that proposal going forward and they will work with the proposal authors and others to make it reality. Core team members do not need to seek consensus to merge a proposal into the draft, but they should listen carefully to concerns from other core team members, as it will be difficult to move the RFD forward if those concerns are not ultimately addressed.
40+
41+
Once a proposal is moved to draft, code and implementation may begin to land into the PR. This work needs to be properly feature gated and marked with the name of the RFD.
42+
43+
Further discussion on the RFD can take place on Slack if needed.
44+
45+
### Moving to the "preview" section
46+
47+
Once the champion feels the RFD is ready for others to check it out, they can open a PR to move the file to the preview section. This is a signal to the community (and particularly other core team members) to check out the proposal and see what they think. The PR should stay open for "a few days" to give people an opportunity to leave feedback. The champion is empowered to decide whether to land the PR. As ever, all new feedback should be recorded in the FAQ section.
48+
49+
### Deciding to accept an RFD
50+
51+
When they feel the RFD is ready to be completed, the champion requests review by the team. The team can raise concerns and notes during discussion. Final decision on an RFD is made by the core team lead.
52+
53+
### Implementation of an RFD
54+
55+
Once accepted, RFDs become living documents that track implementation progress. Status badges in design documentation link back to the relevant RFD, creating a clear connection between "why we're building this" and "how it works." When building code with an agent, agents should read RFDs during implementation to understand design rationale and update them with implementation progress.
56+
57+
## Moderating and managing RFD discussions
58+
59+
Moving RFDs between points in the cycle involve opening PRs. Those PRs will be places to hold dialog and discussion -- but not the only place, we expect more detailed discussions to take place on Slack or other communication channels. RFD owners and champions should actively "curate" discussions by collecting questions that come up and ensuring they are covered in the FAQ. Duplicate questions can be directed to the FAQ.
60+
61+
If the discussion on the PR gets to the point where Github begins to hide comments, the PR should typically be closed, feedback collected, and then re-opened.
62+
63+
# Implementation plan
64+
65+
> What is your implementaton plan?
66+
67+
- ✅ Create RFD infrastructure (about, TEMPLATE, navigation setup)
68+
- ✅ Establish lifecycle: Draft → Preview → Accepted → Completed
69+
- ⏳ Write RFDs for major in-progress features
70+
71+
# Frequently asked questions
72+
73+
## Why "Request for Dialog" and not "Request for Comment"?
74+
75+
Well, partly because "dialog" emphasizes conversation and exploration rather than just collecting feedback on a predetermined design. We also shamelessly stole this process from [Niko Matsakis and the Symposium project](https://symposium-dev.github.io/symposium/rfds/index.html) (with permission) so that we could benefit from their experience.
76+
77+
# Revision history
78+
79+
- 2025-10-28: Initial version, created alongside RFD infrastructure

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
"spellcheck": "./scripts/spellcheck.sh",
2929
"spellcheck:fix": "./scripts/spellcheck.sh --write-changes",
3030
"check": "npm run lint && npm run format:check && npm run spellcheck && npm run build && npm run test",
31-
"docs": "cd docs && npx mint@4.2.93 dev"
31+
"docs": "cd docs && npx mint dev"
3232
},
3333
"devDependencies": {
3434
"prettier": "^3.3.3",

0 commit comments

Comments
 (0)