IPIP-0001: Lightweight Improvement Process for IPFS Specifications

Marcin Rataj GitHub
wilkyr31d GitHub
Related Issue
Commit History
GitHub ipfs/specs (pull requests, new issue, open issues)

This InterPlanetary Improvement Proposal (IPIP) introduces a lightweight "request for comments/change" process for the IPFS specifications repository.

1. Motivation

Today, protocol design discussions often take place in a repository of an IPFS implementation. These conversations are unintentionally obscured from the useful input of Specs Stewards, other implementations, service operators and the wider IPFS Community.

The IPFS Project needs a mechanism for proposing and evaluating specification improvements that are not tied to a specific programming language or implementation of IPFS.

2. Detailed design

Adopt an informal IPIP process for the ipfs/specs repository, providing a minimal structure for opening, reviewing, and merging specification changes.

The purpose of IPIP documents is to document motivation behind the change applied to the spec. IPIP is not to be the spec itself.

To illustrate:

2.1 IPIP Lifecycle

Up-to-date process and IPIP lifecycle will be published in [ipip-process].

2.2 Opening an improvement proposal (IPIP)

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-template.md.

When a new specification file is added to the repo, it should be based on the template at ipfs/specs/template.md.

2.3 Reviewing IPIPs

Specs Stewards will review new IPIP PRs during periodical (best-effort) triage.

IPFS Community is encouraged to participate in the review process.

IPIP can be either:

The final decision belongs to Specs Stewards.

2.4 Merging IPIPs

PR with a IPIP can be merged only after two Specs Stewards approve it and there are no objections from other Stewards.

IPIP number is assigned before the PR merge.

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.

2.5 Long-term plan

Specs Stewards will adjust the process based on usage patterns.

3. Design rationale

We want to empower IPFS community members and implementers with the ability to propose changes in a well-known way, without introducing much overhead.

Guiding principles:

3.1 User benefit

End users will indirectly benefit from a healthy IPIP process being in place:

As a result, IPFS will become easier to implement, useful in more contexts, and benefit more people.

3.2 Compatibility

Existing contents of ipfs/specs repository act as the initial state against which IPIP PRs can be opened.

3.3 Security

Existing Git-based review infrastructure, user accounts and reputation system will be reused.

Merging IPIP will require approval from two Specs Stewards.

3.4 Alternatives

A. References

IPIP: Improvement Process for IPFS Specifications. Marcin Rataj; Guillaume Michel; Henrique Dias. 2023-02-23. URL: https://specs.ipfs.tech/meta/ipip-process/