Part 2 — Shape and Document a Change Chapter 8
Write and Review an RFC
In this chapter
Adding labels sounds like a small change to the Task API. A caller can mark a task as urgent and retrieve it from the list. The moment you add labels to an existing response, that change reaches callers that never asked for labels. A worker that expects exactly id and title can stop reading tasks. The engineer who owns that worker has a question to answer before you decide how to release the feature.
When to write an RFC
An RFC, or request for comments, is a written proposal that gives people a chance to review a change while the important choices are still open. It describes the problem, the proposed approach, the alternatives you considered, and the questions you need reviewers to help answer. The Rust project uses RFCs to discuss substantial changes to the language and its libraries. A team can use the same idea for a change to an internal API.
Write one when the decision needs input beyond the person implementing it. A response change affects consumer teams. A storage migration needs someone to check what happens on restart and recovery. For a validation fix where the expected response is already agreed, the spec and tests can carry that decision into code review. In the labels exercise, the RFC gives the API and client owners room to discuss how the change reaches callers. A spec gives the implementation its observable behavior. An architecture decision record captures a design choice once it has been made.
Write the proposal against the current system
Stay on design-task-labels with notes/task-labels-epic.md and docs/architecture.md committed from the previous exercises. Check the branch and your working tree, then open OpenCode from the lab root.
git branch --show-current
git status --short
opencode
Start a fresh session with /new if one is already open. Select Plan with /agents. Give it the proposal you want to explore and the files that describe the current system.
Draft a request for comments on searchable labels for the Task API.
Read notes/task-labels-epic.md, docs/architecture.md, and src/app.ts.
Propose an in-memory release for the lab. Describe the problem, the
current API, the goal and scope, and the proposed update and filter
requests. Compare adding labels to the existing task response with
an opt-in version and a separate labels resource. Explain what each
would require from callers. Include risks, adoption and rollback,
then ask one question for the client owner and one for the operator.
Keep the durable storage choice open. Mark assumptions and return
the draft in chat, with the files unchanged.
Check the draft against GET /tasks. The current service returns a list of tasks with id and title. In the proposal, PATCH /tasks/:id/labels replaces a task’s labels, and GET /tasks?label=urgent filters the list. The additive option would include a labels array in both the list and task creation responses. Show what one task in the list looks like before and after that change.
{"id":"1","title":"Write a spec"}
{"id":"1","title":"Write a spec","labels":[]}
Those two objects give reviewers a specific compatibility question. Adding a field keeps the current keys available to callers that ignore extra fields. An opt-in version lets a caller choose when to adopt the new shape and gives the service two shapes to support. A separate labels resource preserves the original shape and adds requests for callers that need labels. Put those consequences beside each option so a reviewer can check the assumption about their own client.
Give the draft an adoption condition and a way to reverse the change. For the lab, running the prior revision and checking GET /tasks can confirm that the original response shape is back. Starting that process resets the in-memory state, including tasks, labels, and registrations. State that effect in the rollback section.
Once you’ve reviewed the draft, switch to Build with /agents in the same session.
Save the draft we just reviewed as docs/rfcs/0001-task-labels.md.
Mark it Draft and keep the open questions visible. Edit only that
document. Leave the working changes for me to review and commit.
Run git status --short and check that the RFC is the only changed file. Include the staged diff in your review so you can read the new document before committing it.
git add -- docs/rfcs/0001-task-labels.md
git diff --cached --check
git diff --cached -- docs/rfcs/0001-task-labels.md
git commit -m "Draft the task labels RFC"
Keep the review attached to the draft
Share the draft with a teammate if one is available. Point them to the proposed response and rollout section and ask for an answer you can use. “Does the worker accept the candidate payload above? Which parser or test can we run to check?” gives the client owner a place to start. Ask the operator when they need labels to survive a restart and how they would check that behavior.
For the lab, you can use these two simulated review comments.
Client owner. Our legacy worker rejects task objects with unknown fields. Its compatibility check needs to pass before we can change the response it receives.
Operator. Labels need to survive a restart before production use. Please record who owns the storage decision and how we’ll check recovery.
With the sample comments, try the client owner’s objection against the two example task objects. This small stand-in for the worker expects exactly id and title.
node <<'JS'
const current = { id: "1", title: "Write a spec" };
const proposed = { ...current, labels: [] };
const accepts = (task) => Object.keys(task).sort().join(",") === "id,title";
console.log("Current response accepted", accepts(current));
console.log("Proposed response accepted", accepts(proposed));
JS
Expect true for the current object and false for the proposed one. You can use this result to explain the risk in the RFC. To make a rollout decision for a real caller, run its parser or compatibility suite against the candidate response.
Open a fresh Plan session so the reviewer works from the saved RFC and the comments you paste.
Read docs/rfcs/0001-task-labels.md and review the comments below.
For each comment, identify the part of the RFC it affects and explain
what evidence supports it. Suggest a revision or a follow-up. Flag any
decision that needs the client owner or operator. Return your findings
in chat and leave the RFC unchanged.
Comments and evidence:
<paste the comments and the result of the compatibility check>
Incorporate the feedback
Decide what changes in the proposal before asking Build to edit it. In this exercise, the client owner’s feedback changes the adoption section. The additive response is suitable for the lab’s intended callers. Keep the legacy worker on the existing response until its compatibility check passes or the team agrees on a different response strategy. The operator’s feedback sets a production condition. Leave the lab release in memory and assign the storage decision to the service owner. The follow-up needs restart and restore checks before production use.
In a Review and disposition section, record what you heard, your response, and the place where the reader can see its effect. For the sample comments, two entries might look like this.
| Comment | Disposition | Where it goes |
|---|---|---|
| The worker rejects extra fields. | Incorporated. Legacy rollout depends on its compatibility check. | Adoption section, with the client owner responsible for the check. |
| Labels need to survive restart. | Deferred to the durable release. | Follow-up for the service owner, with restart and restore as acceptance checks. |
If a comment is deferred or declined, give a reason the reviewer can respond to. Keep open questions visible when you still need evidence.
Switch to Build in the review session. The following prompt applies the sample decisions. If you used different comments, give Build your decisions and the sections they affect.
Revise only docs/rfcs/0001-task-labels.md. In Adoption, describe the
in-memory lab audience and require the worker's compatibility check
before changing the response legacy callers receive. In Rollback,
state how restarting resets in-memory tasks, labels, and registrations.
Record the durable production follow-up under Review and disposition,
with the service owner and restart and restore checks. Keep the
original comments and show what changed in response to each one.
Read the diff alongside the draft commit. Look for a change to the adoption condition in the proposal itself. Then check that the rollback steps still make sense and that someone can pick up the durability follow-up from the review record. If you used a real reviewer, send them the revised section and ask them to confirm it addresses the concern they raised.
git diff -- docs/rfcs/0001-task-labels.md
git add -- docs/rfcs/0001-task-labels.md
git diff --cached --check
git commit -m "Address task labels RFC review"
The next chapter uses the revised RFC to record the architecture decision for the durable follow-up. Keep the review record in the RFC so the next reader can see where the restart requirement came from.
References
- The Rust Project. 0002-rfc-process. The Rust RFC Book, RFC 0002, started March 11, 2014.
- The Rust Project. RFC template. First-party repository template.
- OpenCode maintainers. TUI. OpenCode 2 documentation.