|
1 | 1 | # IPIP 0001: Lightweight Improvement Process for IPFS Specifications |
2 | 2 |
|
3 | | -- Start Date: 2022-06-10 |
4 | | -- Related Issues: |
5 | | - - [ipfs/specs/issues/286](https://github.com/ipfs/specs/issues/286) |
6 | | - |
7 | | -## Summary |
8 | | - |
9 | | -This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight |
10 | | -"request for comments/change" process for the IPFS specifications |
11 | | -[repository][1]. |
12 | | - |
13 | | -[1]: https://github.com/ipfs/specs/ |
14 | | - |
15 | | -## Motivation |
16 | | - |
17 | | -Today, protocol design discussions often take place in a repository of an IPFS |
18 | | -implementation. These conversations are unintentionally obscured from the useful input of [Specs Stewards], other |
19 | | -implementations, service operators and the wider IPFS Community. |
20 | | - |
21 | | -The IPFS Project needs a mechanism for proposing and evaluating specification |
22 | | -improvements that are not tied to a specific programming language |
23 | | -or implementation of IPFS. |
24 | | - |
25 | | -## Detailed design |
26 | | - |
27 | | -Adopt an informal IPIP process for the [ipfs/specs][1] repository, providing a |
28 | | -minimal structure for opening, reviewing, and merging specification changes. |
29 | | - |
30 | | -The purpose of IPIP documents is to **document motivation** behind the change |
31 | | -applied to the spec. **IPIP is not to be the spec itself**. |
32 | | - |
33 | | -To illustrate: |
34 | | -- In order to understand how (hypothetical) WebDAV Gateway works, one would |
35 | | - read contents of specs in `ipfs/specs/WEBDAV_GATEWAY.md`. |
36 | | -- IPIP in `ipfs/specs/IPIP/000N-webdav-gateway.md` would only include |
37 | | - **Motivation** and explainer why certain design decisions were made at a |
38 | | - certain point in time. Initial `IPIP/000N-webdav-gateway.md` would explain |
39 | | - why we added WebDAV spec in the first place. |
40 | | -- If we realize the spec has a bug, we will evaluate the impact: adding more |
41 | | - details, test vectors, and editorials/cosmetics can be fixed without IPIP. |
42 | | -- Things that could cause an interop issues require a PR with fix and IPIP in |
43 | | - `ipfs/specs/IPIP/000M-webdav-fix-for-foo.md` explaining why we make the |
44 | | - breaking spec change, compatibility/migration considerations etc. |
45 | | - |
46 | | -### IPIP Lifecycle |
47 | | - |
48 | | -Up-to-date process and IPIP lifecycle will be published in [`ipfs/specs/IPIP_PROCESS.md`](../IPIP_PROCESS.md). |
49 | | - |
50 | | -<details> |
51 | | - <summary>Click to expand the initial (historical) flow</summary> |
52 | | - |
53 | | -### Opening an improvement proposal (IPIP) |
54 | | - |
55 | | -Changes to IPFS specifications can be proposed by opening a Git pull-request |
56 | | -(PR) against the `ipfs/specs` repository. |
57 | | - |
58 | | -In addition to specification changes, such PR must include a short **IPIP |
59 | | -document** based on the template in [`ipfs/specs/IPIP/0000-template.md`](./0000-template.md). |
60 | | - |
61 | | -When a new specification file is added to the repo, it should be based on |
62 | | -the template at [`ipfs/specs/template.md`](../template.md). |
63 | | - |
64 | | -### Reviewing IPIPs |
65 | | - |
66 | | -[Specs Stewards] will review new IPIP PRs during periodical (best-effort) triage. |
67 | | - |
68 | | -IPFS Community is encouraged to participate in the review process. |
69 | | - |
70 | | -IPIP can be either: |
71 | | -- merged, |
72 | | -- rejected (PR close without merging), |
73 | | -- deferred (converting PR back to a draft). |
74 | | - |
75 | | -The final decision belongs to [Specs Stewards]. |
76 | | - |
77 | | -### Merging IPIPs |
78 | | - |
79 | | -PR with a IPIP can be merged only after two [Specs Stewards] approve it and |
80 | | -there are no objections from other Stewards. |
81 | | - |
82 | | -IPIP number is assigned before the PR merge. |
83 | | - |
84 | | -IPIP author and two approving [Specs Stewards] are added to `CODEOWNERS` file |
85 | | -to be automatically asked to review any future changes to files added or |
86 | | -modified by the IPIP. |
87 | | - |
88 | | -</details> |
89 | | - |
90 | | - |
91 | | -### Long-term plan |
92 | | - |
93 | | -[Specs Stewards] will adjust the process based on usage patterns. |
94 | | - |
95 | | -## Design rationale |
96 | | - |
97 | | -We want to empower IPFS community members and implementers with the ability to propose |
98 | | -changes in a well-known way, without introducing much overhead. |
99 | | - |
100 | | -Guiding principles: |
101 | | -- No new tooling |
102 | | - - Reuse Markdown, Git, and existing PR review process |
103 | | -- Convention over Byzantine process |
104 | | - - Proposing a new IPIP should have low cognitive overhead, allowing us to |
105 | | - focus on specs |
106 | | - - Reuse existing GitHub developer accounts and reputation attached to them |
107 | | - - One should be able to create a valid IPIP without reading a long explainer |
108 | | - like this one. Looking at past IPIPs, and then copying a template and |
109 | | - opening a PR with the proposal should be more than enough. |
110 | | - |
111 | | -### User benefit |
112 | | - |
113 | | -End users will indirectly benefit from a healthy IPIP process being in place: |
114 | | - |
115 | | -- IPFS community members will be able to use IPIP drafts for evaluating ideas |
116 | | - before investing time into building new things. |
117 | | -- The bar for creating a brand new IPFS implementation will be lowered, and |
118 | | - existing implementations will be able to propose improvements for others to |
119 | | - adopt. This removes the soft vendor lock-in present when the oldest |
120 | | - implementation is considered as the reference standard and source of truth. |
121 | | -- IPFS implementers will have a better understanding of why certain design |
122 | | - decisions were made, and have both historical context and language-agnostic |
123 | | - specifications with test fixtures ready for use in their project, ensuring |
124 | | - a high level of interoperability. |
125 | | -- More eyes looking at specifications will improve overall quality over time. |
126 | | - |
127 | | -As a result, IPFS will become easier to implement, useful in more contexts, |
128 | | -and benefit more people. |
129 | | - |
130 | | -### Compatibility |
131 | | - |
132 | | -Existing contents of [ipfs/specs][1] repository act as the initial state |
133 | | -against which IPIP PRs can be opened. |
134 | | - |
135 | | -### Security |
136 | | - |
137 | | -Existing Git-based review infrastructure, user accounts and reputation |
138 | | -system will be reused. |
139 | | - |
140 | | -Merging IPIP will require approval from two [Specs Stewards]. |
141 | | - |
142 | | -### Alternatives |
143 | | - |
144 | | -- Maintaining the status quo (no IPIP process) is not acceptable, as we want to |
145 | | - move specification discussions away from repositories of specific |
146 | | - implementations. We need a mechanism for discussing improvements that is not |
147 | | - tied to specific implementation or language. |
148 | | -- Creating more elaborate IPIP process. This comes with increased overhead and |
149 | | - risk. Introducing a complex process requires deeper understanding of |
150 | | - community needs and pitfalls of preexisting processes, and since we don't |
151 | | - have any process in place, starting light, limits the risk. |
152 | | - |
153 | | -### Copyright |
154 | | - |
155 | | -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). |
156 | | - |
157 | | -[Specs Stewards]: https://github.com/orgs/ipfs/teams/specs-stewards/members |
| 3 | +Moved to https://specs.ipfs.tech/ipips/ipip-0001/ |
0 commit comments