RFC Process¶

This document describes the Request for Comments (RFC) process for proposing substantial changes to MAID.

What is an RFC?¶

An RFC (Request for Comments) is a design document that describes a proposed change to MAID. RFCs provide a consistent and controlled way to propose new features, architectural changes, or process improvements.

The RFC process ensures that:

Significant changes are well-thought-out before implementation
The community has opportunity to provide input
Decisions are documented for future reference
Contributors understand the "why" behind changes

When to Write an RFC¶

You SHOULD write an RFC for:

New features that add significant functionality
Changes to public APIs
Architectural changes affecting multiple packages
Changes to the content pack protocol
New content pack system capabilities
Breaking changes to existing functionality
New dependencies on external services
Changes to the project's governance or processes

You DO NOT need an RFC for:

Bug fixes
Documentation improvements
Code refactoring that doesn't change behavior
Performance improvements with no API changes
Adding tests
Minor feature enhancements (use your judgment)

When in doubt, open a GitHub Discussion to ask if an RFC is needed.

RFC Lifecycle¶

┌─────────────┐
│   Draft     │ ← Initial proposal
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  In Review  │ ← Community feedback period
└──────┬──────┘
       │
       ├──────────────┐
       ▼              ▼
┌─────────────┐ ┌─────────────┐
│  Accepted   │ │  Rejected   │
└──────┬──────┘ └─────────────┘
       │
       ▼
┌─────────────┐
│ Implementing│ ← Being built
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Complete   │ ← Shipped!
└─────────────┘

How to Submit an RFC¶

1. Create an Issue¶

Open a new GitHub Issue using the RFC template:

Title: RFC: <Short Description>
Label: rfc

2. Fill Out the Template¶

Use the template below to structure your RFC.

3. Gather Feedback¶

Share in GitHub Discussions for early feedback
Link to the RFC in relevant issues
Discuss in community channels (Discord, planned)

4. Revise Based on Feedback¶

Update the RFC based on community input. Significant changes should be noted in a "Revision History" section.

5. Request Review¶

When ready, request review from maintainers by commenting on the issue.

6. Decision¶

Core maintainers will review and decide to:

Accept: The RFC is approved for implementation
Reject: The RFC is declined (with explanation)
Defer: The RFC is valid but not a current priority

RFC Template¶

# RFC: [Title]

## Summary

[One paragraph explanation of the feature]

## Motivation

[Why are we doing this? What problem does it solve? What use cases does it support?]

## Detailed Design

[This is the bulk of the RFC. Explain the design in enough detail that:

- Its interaction with other features is clear
- It is reasonably clear how the feature would be implemented
- Edge cases are considered

Include code examples where helpful.]

## Drawbacks

[Why should we NOT do this? Are there any downsides?]

## Alternatives

[What other designs have been considered? Why was this design chosen?]

## Unresolved Questions

[What aspects of the design are still TBD? What would you like feedback on?]

## Implementation Plan

[How will this be implemented? Break into phases if large.]

### Phase 1
- [ ] Task 1
- [ ] Task 2

### Phase 2
- [ ] Task 3

## Revision History

| Date | Change |
|------|--------|
| YYYY-MM-DD | Initial draft |

Review Process¶

Community Review Period¶

All RFCs have a minimum 1-week community review period. Complex RFCs may have longer review periods.

During this time:

Anyone can comment with feedback
The author should respond to questions
Revisions are encouraged

Maintainer Review¶

After community review, maintainers will:

Evaluate technical merit: Is the design sound?
Assess scope: Is this the right size for an RFC?
Check alignment: Does it align with project goals?
Review completeness: Are all sections addressed?

Decision Criteria¶

RFCs are evaluated based on:

Value: Does it solve a real problem?
Feasibility: Can it be implemented reasonably?
Compatibility: Does it work with existing systems?
Maintainability: Will it be sustainable long-term?
Community support: Is there consensus?

Voting¶

Core maintainers vote on RFC acceptance:

Requires majority approval
At least 2 core maintainers must review
Any maintainer can veto with strong objection (requires discussion)

After Acceptance¶

Once an RFC is accepted:

Assign implementation: A contributor (often the RFC author) is assigned
Create tracking issue: Link implementation tasks to the RFC
Update RFC status: Mark as "Implementing"
Implementation: Build the feature following the design
Documentation: Update docs as needed
Mark complete: Close the RFC issue when shipped

Changing Accepted RFCs¶

If significant changes are needed to an accepted RFC:

Minor clarifications: Edit the RFC directly
Significant changes: Open a new RFC that supersedes the original
Implementation learnings: Document deviations in the RFC

RFC Archive¶

All RFCs (accepted, rejected, and deferred) are preserved for historical reference. You can find them by searching GitHub Issues with the rfc label.

Examples¶

Here are examples of what good RFCs look like:

Good RFC: Clear problem statement, detailed design, considered alternatives
Needs work: Vague motivation, incomplete design, missing drawbacks

Note: As MAID is a newer project, we're building our RFC archive. Early RFCs will serve as templates for future proposals.

Questions?¶

If you have questions about the RFC process:

Open a GitHub Discussion
Ask a maintainer
Check existing RFCs for examples

This RFC process is inspired by the Rust RFC process, Python PEPs, and React RFCs.