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
We adopted a formal change management process for the ipfs/specs repository, providing a minimal structure for opening, reviewing, and merging specification changes.
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 a specification.
To illustrate:
- In order to understand how (hypothetical) WebDAV Gateway works, one would
read contents of specs in
ipfs/specs/WEBDAV_GATEWAY.md. - IPIP in
ipfs/specs/IPIP/000N-webdav-gateway.mdwould only include Motivation and explainer why certain design decisions were made at a certain point in time. InitialIPIP/000N-webdav-gateway.mdwould explain why we added WebDAV spec in the first place.
- 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:Things that could cause an interop issues require a PR with fix and IPIP in
ipfs/specs/IPIP/000M-webdav-fix-for-foo.mdexplaining why we make the breaking spec change, compatibility/migration considerations etc.
Changes to IPFS specifications can be proposed by opening a Git pull-request
(PR) against the ipfs/specs repository.
In addition to specification changes, such PR must include a short IPIP
document based on the template in ipfs/specs/IPIP/0000-template.md.
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
- 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
mainbranch. Potentially useful (but rejected for now) proposals should be also merged tomain, 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
CODEOWNERSfile to be automatically asked to review any future changes to files added or modified by the IPIP.
Specs Stewards will adjust the process based on usage patterns.
Copyright and related rights waived via CC0.