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 protected]>
: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.