RFC and Specification Workflow Infrastructure

[nikomatsakis]

RFC and Specification Workflow Infrastructure

Status: In Progress

Current Understanding

Established comprehensive RFC and specification workflow for Dada language development. RFC-0002 documents the design using MyST directive syntax for spec paragraphs.

Next Steps

• Convert existing spec files from r[...] to :::{spec} directive syntax
• Update spec validation tooling to parse MyST directives
• Create interactive specification viewer with RFC toggles

Open Questions

• None currently

Context

RFC-0002 serves as canonical reference documenting the entire workflow. Spec paragraphs use MyST syntax: :::{spec} paragraph.id [rfcN...] [!rfcN...]. Infrastructure includes:

• mdbook for RFCs at dada-lang.org/rfcs with auto-population
• mdbook for spec with custom preprocessor handling {spec} directives
• Test-spec linking with #:spec annotations
• cargo xtask rfc new command for RFC creation

[nikomatsakis]

Session summary (Initial Planning Phase):

• Started planning RFC and specification workflow for Dada
• Goal: Make RFCs/specs visible, use lightweight tools, separate concerns

Key decisions made:

• Storage: rfcs/ and spec/ as mdbooks, book/ remains Docusaurus
• mdbook chosen over Docusaurus for lighter weight approach
• RFCs remain permanently as historical records, organized by status
• Simple sequential numbering (0001, 0002, etc.)
• RFC subdirectories contain README.md, implementation.md, spec-draft.md

Impact on approach:

• Decided on manual spec integration with staging in RFC directories
• Spec remains authoritative; RFCs provide teaching/motivation
• Front matter tracks RFC status and implementation version

[nikomatsakis]

Session summary (2025-06-02 - Infrastructure Implementation):

• Created both rfcs/ and spec/ mdbook structures
• Updated cargo xtask deploy to build all three sites
• Implemented paragraph labeling with r[...] syntax
• Created dada-mdbook-preprocessor for processing labels

Key discovery:

• mdbook preprocessors cannot modify configuration dynamically
• Implemented inline CSS injection approach instead
• Preprocessor scans chapters, processes labels, injects styles

Progress: Completed basic infrastructure setup. Next: RFC template and workflow.

[nikomatsakis]

Session summary (2025-06-03 - RFC Template and Tooling):

• Created RFC-0000 template as concise skeleton
• Implemented cargo xtask rfc new command with auto-numbering
• Updated .development/rfc.md workflow documentation

Session summary (Auto-populate SUMMARY.md):

• Modified preprocessor to scan RFC directories and populate book structure
• Pattern inspired by rust-project-goals preprocessor
• Implemented directory scanning, title extraction, chapter creation
• SUMMARY.md now uses [All RFCs <\!-- populate -->]() format

Progress: RFC creation tooling complete. Next: enhance RFC browsing experience.

[nikomatsakis]

Session summary (2025-06-13 - Enhanced RFC Browser):

• Created beautiful "All RFCs" page with GitHub-inspired styling
• Implemented status-based categorization (Active, Accepted, Implemented, Draft, Rejected)
• Added shields.io status badges
• Collapsible summary rows with disclosure triangles
• Dark theme support

Key improvements:

• Extract status from RFC front matter
• Generate formatted HTML tables
• Strategic newlines for markdown processing in HTML
• CSS injection system for styling

Progress: RFC browsing interface polished. Next: document the process itself.

[nikomatsakis]

Session summary (2025-06-16 - RFC-0002 Meta-RFC):

• Created RFC-0002 documenting the RFC process itself
• Resolved all major design decisions from previous sessions
• Comprehensive tooling comparison between mdbook and Sphinx

Key design elements finalized:

1. RFC annotation system: rfc[123] tags on spec paragraphs
2. Interactive spec viewer with expandable RFC sections
3. Test integration with prefix matching
4. Recommended custom Sphinx extension approach

RFC structure validated:

• Used RFC process to document itself
• Removed spec.md from template (specs go in main spec)
• Documented complete lifecycle

Progress: RFC-0002 complete. All design decisions resolved. Ready for implementation phases.

[nikomatsakis]

Session summary:

• Reviewed RFC-0002 implementation status
• Redesigned spec paragraph syntax to use MyST directives

Key changes to RFC-0002:

• Replaced r[...] + rfc[123] with :::{spec} paragraph.id rfcN directive
• Added !rfcN prefix for content deleted by an RFC
• Committed to MyST/Sphinx tooling approach
• Added FAQ explaining MyST choice

Progress: RFC-0002 updated (commit 08a43a0). Next: convert existing spec files to new format.