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
On a branch, run make new TITLE="..." to start the next RFD from the
template, which
creates rfd/NNNN/README.adoc and its implementation checklist, already
linked to each other. The template’s comments describe what a good RFD covers.
Every RFD answers three questions first:
-
Goal: what is true once the RFD is done, and for whom.
-
Problem: what is wrong or missing today, with the evidence.
-
Objectives: the outcomes that decide whether the proposal worked, and what it deliberately leaves out.
The Proposal then explains how the objectives are met. Alternatives, supporting material such as data or proof-of-concept results, and open questions are there when they help; rename, drop, or add sections as the topic needs. Above all, 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.
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 go through a new
pull request and retain the original discussion link unless the RFD explicitly
documents a replacement. Changes that supersede a committed or abandoned RFD use
a new RFD and cross-link the historical decision.
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@example.com>
:state: prediscussion
:discussion:
:labels: toudai, software, process
= RFD 5 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 index intentionally does
not duplicate it.
An RFD is public unless it sets :visibility: private. A private RFD’s page,
and its place in the lists, appear only to readers who have signed in; a public
RFD must not link to a private one. Labels and visibility are
the attributes that may change after an RFD is committed or abandoned.
Implementation progress lives separately in rfd/NNNN/IMPLEMENTATION.adoc,
following the AsciiDoc checklist convention; the checker also accepts the
legacy IMPLEMENTATION.org and IMPLEMENTATION.md formats, and an RFD must
have exactly one format.
The RFD and checklist link to each other, keeping design and decision history
stable while implementation tasks are checked off.
An RFD that mentions another RFD links to it with an AsciiDoc cross-reference,
such as xref:../0005/README.adoc[RFD 5], or
RFDs xref:../0013/README.adoc[13] and xref:../0014/README.adoc[14]. The
link resolves both on GitHub and on the site, where it points to that RFD’s
page. A link to a section adds the section’s id, such as
xref:../0005/README.adoc#_goal[RFD 5's goal]; a reference within an RFD
uses the id alone, such as <<_goal>>. Section ids are Asciidoctor’s
defaults: _ followed by the lowercased title with _ between words, so
== Goal and scope is _goal_and_scope. An explicit anchor such as
[[support-access]] keeps the id it names. Links between an RFD and its own
checklist stay link:IMPLEMENTATION.adoc[...] and link:README.adoc[...].
make link-rfds links every unlinked mention, and make check-rfds rejects
unlinked mentions, link: between RFDs, links to RFDs or sections that do not
exist, and cross references to sections an RFD does not have. Mentions in
titles, comments, attributes, inline literals, and listing blocks are left
alone. Linking a mention, replacing link: with xref:, changing a section
reference’s target, or rewrapping lines is not a change to a final RFD.
Run make check-rfds to validate source layout, metadata, state, title, and the
checker’s tests, and make status to list each RFD’s progress. CI also supplies
RFD_BASE_REF on pull requests so the checker can reject lifecycle regressions,
historical deletion, and changes to final RFDs against the pull-request base. A
local review can do the same with RFD_BASE_REF=<git-revision> make check-rfds.
The Progress column reports the percentage of checklist tasks completed; state
describes the decision’s lifecycle rather than duplicating that implementation
count.
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 before a
final state.
Checklist progress never changes state automatically, but committed requires a
non-empty checklist with every task complete.
prediscussion and ideation may move between each other or advance to any
later state. discussion may advance to published, committed, or
abandoned; published may advance to committed or abandoned. Published and
committed decisions never regress to drafting states. A committed or abandoned
RFD is immutable: replace or supersede it with another RFD rather than rewriting
its lifecycle.
Experiments and migrated history
RFD 1 came from toudai-dev/toudai. Its six former section checklists now form
six groups in IMPLEMENTATION.adoc; the old paths link to those groups. Task
text and completion state are preserved. Design sections, decisions, experiment
records, harnesses, and recorded results retain their paths. Never rewrite
recorded results to match newer product behavior.
Experiment harnesses may need a version-matched Toudai checkout. See the migration guide for checkout selection and the files retained by the product tests.