What are you proposing to change? Bullet points welcome.
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.
How do things work today and what problems does this cause? Why would we change things?
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.
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.
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.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.
The PR is merged into “draft” once a core team member decides to champion it
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.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.Further discussion on the RFD can take place on Slack if needed.
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.
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.
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.
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.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.
Why “Request for Dialog” and not “Request for Comment”?
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 (with permission) so that we could benefit from their experience.
