Chaba RFDs

Process

Requests for Discussion (RFDs) capture ideas early enough to shape them through written discussion and preserve the reasoning behind decisions. An RFD is not authoritative merely because it exists; its state says how it should be read.

Writing an RFD

Reserve the next unused four-digit number and, on a branch, create rfd/NNNN/README.adoc and its implementation checklist, rfd/NNNN/IMPLEMENTATION.adoc. Both are AsciiDoc. Cross-link the two documents. Write for someone who was not in the room: lead with the conclusion, keep paragraphs short, and use plain words.

Use prediscussion while writing, or ideation for a topic placeholder. When the document is ready for review, open a pull request, set the state to discussion, and add that pull request as the discussion URL. Every pull request gets a preview of the site, linked from the pull request.

Before merging a proposal that represents project direction, move it to published. Once the described work is entirely implemented, update it to committed. Material changes to a published or committed RFD use a new pull request and retain the original discussion link unless the RFD documents a replacement.

Source format

Each RFD lives at rfd/NNNN/README.adoc, where NNNN is a four-digit number. The document starts with canonical AsciiDoc attributes and an unpadded title:

:authors: Name <[email protected]>
:state: prediscussion
:discussion:
:labels: project, software, process

= RFD 7 Example title

authors contains semicolon-separated owners. discussion contains the RFD’s pull-request URL once discussion starts. labels is a comma-separated set of searchable topics, starting with the project the RFD belongs to. The document is the single source of truth for this metadata; the site reads it from the attributes, so RFDs have no front matter.

An RFD is private when it belongs to a private source project or sets :visibility: private. A private RFD’s page and its place in the lists appear only to members of the chaba-dev GitHub organization who have signed in. Private projects themselves are also left out of the project filter until the reader signs in.

Implementation progress lives separately in the checklist, so the design and decision record stay stable while tasks are checked off. It starts with = RFD NNNN implementation checklist, links back with RFD N: Title, and lists one task per change that can land on its own, as AsciiDoc checklist items such as * [ ] Task and * [x] Done. The site shows the share of checked tasks as the RFD’s implementation progress.

Cross-references

Every mention of another RFD is an AsciiDoc cross-reference to it:

The protocol is defined in xref:../0002/README.adoc[RFD 2], and replay in
xref:../0002/README.adoc#_replay[RFD 2's replay rules].

The link resolves both on GitHub and on the site, where it points to that RFD’s page. A fragment names a section by Asciidoctor’s default ID: followed by the lowercased title with between words. Name each RFD separately: write "RFD 1 through RFD 4" with a link on each, not "RFDs 1 through 4".

States

  • prediscussion: actively being written and not ready for broad review.

  • ideation: a narrowly scoped topic or scratchpad without active revision.

  • discussion: under active review in the linked pull request.

  • published: discussion has converged and the RFD expresses project direction.

  • committed: the proposal is fully implemented and describes current behavior.

  • abandoned: deliberately not proceeding or retained only for history.

The usual path is prediscussion or ideation to discussion, then published, and eventually committed. abandoned is an off-ramp at any stage. Checklist progress does not determine an RFD’s state.