Design proposals ("Requests for Comments") for CoMapeo — covering comapeo-core, the mobile and desktop apps, and the protocols and data formats they share.
An RFC is a design document: a written proposal for a substantial change, reviewed in a pull request before anyone writes the implementation. It records not just what we intend to build but why — the motivation, the alternatives considered and rejected, the security implications, and the migration path. Once merged, an RFC is the authoritative record of a design decision; the PR serves as a record of the discussion that led to it.
Open an RFC for changes that are expensive to reverse or that others must build against:
- Changes to wire protocols, handshake or sync behaviour, or anything affecting interop between app versions
- Changes to data formats, schemas, or the encryption/key model
- New protocols or subsystems (discovery mechanisms, transports, invite flows)
- Anything with meaningful security or privacy implications
- Cross-cutting changes that span core and the apps
You do not need an RFC for bug fixes, refactors, performance work, dependency updates, or additive features that don't touch the categories above. When in doubt, open an issue and ask.
- Discuss first (optional but recommended). For anything non-trivial, open an issue or start a conversation before writing. A rough sketch that gets early feedback beats a polished proposal built on a wrong assumption.
- Branch and copy the template. Copy
0000-template.mdtotext/0000-short-title.md, keeping the0000prefix for now. - Write the RFC. Fill in the template. The Motivation, Rationale and alternatives, and Drawbacks sections matter as much as the design itself — an RFC that only describes a design, without the reasoning around it, isn't ready for review. Not every section fits every proposal; drop what doesn't apply (see RFC 0003 for a deliberately smaller exploratory RFC). You don't need every section polished before opening the PR — a rough draft the team can react to is fine.
- Open a pull request. The PR number becomes the RFC number: rename the file to
text/NNNN-short-title.mdand update the document header to match, in a follow-up commit. Revise the RFC text in response to comments and discussion in the PR. When a thread is resolved, fold the conclusion back into the document — future readers should not need the comment thread to understand the design. - Reach a decision. When discussion has settled, a maintainer announces the intended outcome (merge, close, or postpone) and leaves a final comment period of about a week for last objections. Then the RFC is merged with its
Statusupdated to Accepted, or closed with a comment explaining why. - Implement. Acceptance means the design is agreed, not that anyone is committed to building it on a schedule. When an RFC is merged, open a tracking issue in each repo it lists as affected, linking back to the RFC, and add the issue links to the RFC's header — the RFC stays the map of where the work is happening, while each repo's contributors see the work in their own tracker.
| Status | Meaning |
|---|---|
| Draft | Open PR, under review |
| Accepted | Merged; the agreed design |
| Implemented | Shipped in the referenced repos |
| Superseded | Replaced by a later RFC (link it) |
An accepted RFC can still change: small corrections and clarifications go in follow-up PRs to this repo; a change to the substance of the design needs a new RFC that supersedes or amends the old one.
text/— the RFCs, one file each, numbered0000-template.md— the template for new RFCs
CoMapeo is open source, and protocol and privacy design benefits from outside scrutiny — default to writing RFCs in the open. If a proposal needs to incubate privately first (for example, it describes an unmitigated security issue), draft it internally and open it once it's ready for wider review.
RFC text is licensed under CC-BY 4.0.