Skip to main content

RFC Process

RFC = Request for Comments

RFCs are the mechanism for proposing significant changes to Framework M. They ensure that major decisions are documented, discussed, and deliberated before implementation.

When to Write an RFC​

Required for:

  • New Protocols (Ports) in the core
  • Breaking changes to existing APIs
  • New adapters that ship with core
  • Significant architectural changes
  • New CLI commands or major flags
  • Changes to the metadata/DocType system

Not required for:

  • Bug fixes
  • Performance improvements (without API change)
  • Documentation updates
  • Refactoring (without behavioral change)
  • New adapters in separate packages

RFC Lifecycle​

┌─────────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐     ┌────────────┐
│  Draft  │ ──► │ Review  │ ──► │ Accepted │ ──► │ Merged   │ ──► │ Implemented│
└─────────┘     └─────────┘     └──────────┘     └──────────┘     └────────────┘
                     │                                                   │
                     ▼                                                   ▼
               ┌──────────┐                                       ┌───────────┐
               │ Rejected │                                       │ Superseded│
               └──────────┘                                       └───────────┘
StatusMeaning
DraftUnder active authoring
ReviewOpen for community feedback (minimum 14 days)
AcceptedTSC approved, ready for implementation
RejectedTSC declined with documented rationale
MergedImplementation MR merged
ImplementedFully released
SupersededReplaced by a newer RFC

Process​

1. Create RFC Draft​

  • GitLab First: Follow the branching and template instructions below.
  • Placeholder: Use rfc-0000-name.md as the filename.

2. Propose & Open Discussion​

  • GitLab MR: Open a Merge Request on GitLab. This is the Source of Truth for the specification text.
  • Community Forum (Apache Answer):
    • Create a new "Discussion" post on the Community Forum.
    • Header: Copy the RFC Summary and Motivation.
    • Linkage:
      • The Forum post must link to the GitLab MR.
      • The GitLab MR description must link to the Forum post.
    • Single Source of Discussion: All deep-dive feedback and community voting happens on the Forum. GitLab comments should be limited to specific code/markdown line reviews.

3. Review Period​

  • Minimum 14 days for review.
  • The author updates the GitLab MR based on the consensus reached on the Forum.
  • Cross-Posting: Major changes to the draft on GitLab should be summarized as a reply in the Forum thread to keep everyone informed.

4. Decision & Finalization​

  • TSC Decision: The Technical Steering Committee reviews the Forum thread and GitLab spec.
  • Merge: Once approved, the maintainer assigns the final RFC number, renames the file, and merges the MR.
  • Archive: The Forum thread is marked as "Accepted" or "Closed" with a link to the final merged RFC file in the documentation site.

RFC Template Structure​

Every RFC must include a Discussion Link in its frontmatter:

- **Status**: Proposed
- **Author**: @username
- **Discussion**: [Link to Forum Post]
- **Created**: YYYY-MM-DD

Tips for Authors​

  1. Sync frequently: If the forum discussion changes the design, update the GitLab MR immediately.
  2. One Conversation: Discourage users from starting separate threads on Discord or Telegram. Redirect them to the Forum so the conversation is preserved for future contributors.
  3. Summary is Key: Most forum users will read the summary/motivation first. Make it compelling.

See rfc-template.md.

RFC Numbering​

  • To avoid race conditions, RFCs are assigned numbers sequentially by the maintainers when the PR is merged (or approved).
  • When creating a new RFC draft, use 0000 as a placeholder number in the filename (e.g., 0000-your-proposal-name.md or rfc-0000-your-proposal-name.md) and within the document title.
  • The core team will rename the file and update the title to the next available sequential number (0001, 0002, etc.) before merging.
  • Rejected RFCs may be assigned a number upon rejection for the public record.

Where RFCs Live​

docs/rfcs/
├── 0001-protocol-versioning.md
├── 0002-virtual-doctype-api.md
└── ...

Tips for Authors​

  1. Start with the problem, not the solution
  2. Be specific — avoid vague proposals
  3. Consider alternatives — show you've thought about other approaches
  4. Keep it focused — one major change per RFC
  5. Anticipate questions — address likely objections upfront