IPIP aims to focus protocol design discussions into an orderly process that:
Provides good visibility into to the full set of proposals
Keeps the full discussion for a proposal in one place, providing historical context
Ensures stakeholders in the project can be aware of proposed changes and participate
in the decision making process
Provides a mechanism to ensure proposals are given consideration and decisions get made
2. Process design
We adopted a formal change management process for the ipfs/specs repository, providing a
minimal structure for opening, reviewing, and merging specification changes.
2.1 What is an IPIP?
IPIP Provides an orderly mechanism for considering proposed changes to IPFS specifications.
An IPIP proposal is not to be the spec itself; the approval of an IPIP leads to an update to
In order to understand how (hypothetical) WebDAV Gateway works, one would
read contents of specs in ipfs/specs/src/webdav-gateway.md.
IPIP in ipfs/specs/src/ipips/ipip-000N.md would only include
Motivation and explainer why certain design decisions were made at a
certain point in time. Initial ipip-000N.md would explain
why we added WebDAV spec in the first place.
2.2 What changes need the IPIP process?
Does Not Need IPIP: The spec has a bug - something that is plainly a mistake
Does Not need IPIP: Adding more details, test vectors, and editorials/cosmetic changes
Needs IPIP: An addition to the protocol
Needs IPIP that could cause an interop issues require a PR with fix and IPIP in
ipfs/specs/src/ipips/ipip-000M.md explaining why we make the
breaking spec change, compatibility/migration considerations etc.
3. Improvement lifecycle
3.1 Opening an improvement proposal (IPIP)
Changes to IPFS specifications can be proposed by opening a Git pull-request
(PR) against the ipfs/specs repository.
When a new specification file is added to the repo, it should be based on
the template at ipfs/specs/template.md.
When naming a new proposal, don't try to introduce an IPIP number; we will do that only for
IPIPs that are approved before accepting into main branch.
Proposals are officially submitted when a pull request into main is opened
Proposals that were reviewed as useful, but rejected for now, will be moved into IPIP/deferred folder and then merged into main
3.2 Reviewing IPIPs
Specs Stewards will do an initial triage of newly opened PRs roughly monthly. They'll try to filter out
noise, so that community consideration is given only to reasonable proposals; others they'll reject.
Specs Stewards will post to the forums linking to the proposal; directing feedback/discussion to
take place in GitHub on the PR
After a month of discussion, Specs Stewards will review again. If there are no substantive disagreements
with the proposal, including within Spec Stewards, the proposal will be approved.
If discussion or modification is still underway and appears to be leading to a resolution, it can be held
open for another month
Proposals that are generating ongoing discussion and seem contentious or stuck will be brought in for
consideration at a monthly sync, to be announced at least a week ahead of time on the forum.
After discussion, Spec Stewards will make call on whether to approve or reject the proposal.
At this point approved proposals get assigned a number (encoded in the filename),
and merged into the IPIP folder on main branch. Potentially useful (but rejected for now)
proposals should be also merged to main, but in a subfolder called /IPIP/deferred. Proposals rejected in initial
triage will simply have the PR declined.
IPIP author and two approving Specs Stewards are added to CODEOWNERS file to be
automatically asked to review any future changes to files added or modified by the IPIP.