How proposals are raised, discussed, and accepted into the specification.
This page describes how changes are made to the Core Protocol and Companion Protocol specifications. The process is designed to be lightweight, transparent, and tied to running code wherever possible.
- Interoperability is the product. Any change that breaks interoperability without a clear migration path is rejected by default.
- Rough consensus, running code. A proposal moves forward when there is broad agreement from active implementers and at least one working implementation. A single objection is not a veto, but objections must be addressed on the record.
- Everything is public. There are no closed meetings, private mailing lists, or embargoed decisions. If something happened off the record, it didn’t happen.
We are on irc.libera.chat in the channels #coreprotocol and #coreprotocol-dev.
You can chat without an account or special client software by using the web client.
Subscribers can join by sending email to coreprotocol-request at freelists.org with ‘subscribe’ in the Subject field or by visiting here.
You can send to the list without subscribing by sending to coreprotocol at freelists.org and there is an archive available here.
You can participate without any formal membership. The three main places work happens are:
- Issues — for bug reports against the specification (ambiguity, contradiction with deployed behaviour, missing detail), raise an issue. No proposal is required.
- Proposals — for any substantive change — a new payload type, a change to framing, a new command, a deprecation — open a proposal. See the template below.
- Discussion — general discussion, questions, and design conversation happen in the chat channels and on the mailing list. Technical decisions, however, are only binding when they land in an accepted proposal.
All issues SHOULD go to the mailing list, proposals MUST go to the mailing list and discussion MAY occur anywhere.
Every proposal moves through a small set of stages. A proposal can be withdrawn or rejected at any stage; it can also be sent back to an earlier stage if new information arises.
- DraftAuthor writes the proposal and opens it for comment. The goal at this stage is to make the proposal readable, motivated, and concrete.
- DiscussionThe working group reviews the proposal. Feedback happens in the open. The author revises. Implementers raise concrete concerns — what breaks, what gets harder, what gets easier.
- ExperimentalAt least one implementation exists and can interoperate with a reference implementation. The proposal is marked experimental in the draft specification. Other implementers are invited to try it.
- Last callThe editor announces a final review period — typically two weeks. Remaining objections must be stated during this window. Silence is taken as assent.
- AcceptedThe proposal is merged into the specification. The specification version is bumped according to the compatibility rules below. The proposal remains archived for reference.
A good proposal is short, specific, and answers the right questions. Use roughly this shape:
# Title
## Summary
One paragraph. What is being changed?
## Motivation
Why is the current specification inadequate? What real use case or
failure mode prompted this? If possible, name the deployments or
implementations affected.
## Specification
The concrete text to add, change, or remove. Quote the sections of
the specification being edited. Use the same conventions (§1 of the
specification).
## Compatibility
- Does this change packet format, framing, or command codes?
- Is it backwards-compatible with nodes running an older version?
- What is the migration path?
- What version of the specification does this target?
## Reference implementation
A link to code, a branch, or a prototype that implements the proposal.
Running code is strongly preferred; a design without an implementation
will usually be asked to produce one before leaving Discussion.
## Prior discussion
Links to related issues, chat threads, or earlier proposals.
The specification uses a simple two-number version: MAJOR.MINOR.
- Minor version bumps for additive, backwards-compatible changes — new optional payload types, new optional commands, new reserved fields, clarifications, errata. A node built against an older minor version will still interoperate with a node built against a newer one.
- Major version bumps for changes that are not backwards-compatible — wire-format breaks, mandatory new fields, removed commands, cryptographic changes. A major version bump requires an explicit migration strategy and is reserved for situations where no backwards-compatible design is possible.
Every accepted proposal must state which kind of change it is. If the classification is contested, the editor decides during Last call.
The working group is deliberately flat. There are only two roles:
- Editor. Maintains the specification document, merges accepted proposals, publishes releases, and announces Last call windows. The editor does not decide technical questions; they record decisions.
- Contributor. Everyone else — anyone raising issues, writing proposals, implementing the specification, or reviewing others’ work.
Editors are selected by the working group and rotate periodically. There is no permanent chair.
Current editor during initial draft implementation: Enot (ded) Skelly ~ enot AT mail box DOT org.
Discussion is technical, not personal. Disagree with the proposal, not the author. Assume good faith. If you see behaviour that falls short of this, contact an editor.