From fbeb0339f33a4b925ca563ab2155decd9b6da0cc Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 14 Jun 2022 16:09:46 +0200 Subject: [PATCH 01/10] RFC 0001: lightweight RFC process --- RFC/0000-template.md | 63 +++++++++++++++ RFC/0001-lightweight-rfc-process.md | 117 ++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 RFC/0000-template.md create mode 100644 RFC/0001-lightweight-rfc-process.md diff --git a/RFC/0000-template.md b/RFC/0000-template.md new file mode 100644 index 000000000..4bed54750 --- /dev/null +++ b/RFC/0000-template.md @@ -0,0 +1,63 @@ +# RFC 0000: Request for Change Template + + + +- Start Date: (format: YYYY-MM-DD) +- Related Issues: + - (add links here) + +# Summary + + +This is the suggested template for new RFCs. + +# Motivation + +AKA Problem Statement + +Clearly explain why the existing protocol specification is inadequate +to address the problem that the RFC solves. + +# Detailed design + +AKA Solution Proposal + +Describe the proposed solution and list all changes made to the specs repository. + +The resulting specification should be detailed enough to allow competing, +interoperable implementations. + +## Test fixtures + +List relevant CIDs. Describe how implementations can use them to determine +specification compliance. + +## Design rationale + +The rationale fleshes out the specification by describing what motivated +the design and why particular design decisions were made. + +Provide evidence of consensus within the community, +and discuss important objections or concerns raised during discussion. + +### User benefit + +How will end users benefit from this work? + +### Compatibility + +Explain the upgrade considerations for existing implementations. + +### Security + +Explain the security implications/considerations relevant to the proposed change. + +### Alternatives + +Describe alternate designs that were considered and related work. + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/RFC/0001-lightweight-rfc-process.md b/RFC/0001-lightweight-rfc-process.md new file mode 100644 index 000000000..744e865be --- /dev/null +++ b/RFC/0001-lightweight-rfc-process.md @@ -0,0 +1,117 @@ +# RFC 0001: Lightweight RFC Process for IPFS Specifications + +- Start Date: 2022-06-10 +- Related Issues: + - [ipfs/specs/issues/286](https://github.com/ipfs/specs/issues/286) + +# Summary + +This Request for Change (RFC) introduces lightweight RFC process +for IPFS specifications [repository][1]. + +[1]: https://github.com/ipfs/specs/ + +# Motivation + +Protocol design discussions often take place in a repository of an IPFS +implementation. Often lacking useful input from IPFS Stewards, other +implementations, service operators and the wider IPFS Community. + +IPFS Project needs a mechanism for proposing and evaluating specification +improvements that are not tied to a specific programming language +or implementation of IPFS. + +# Detailed design + +Adopt an informal RFC process for [ipfs/specs][1] repository, providing +minimal structure for opening, reviewing, and merging specification changes. + +## Opening + +Changes to IPFS specifications can be proposed by opening a PR against the +repository, and including a short "request for change" document based on the +template in `RFC/0000-template.md`. + +## Reviewing + +IPFS Stewards will review new RFC PRs during weekly triage. + +IPFS Community is encouraged to participate in the review process. + +Final decision belongs to IPFS Stewards. + +## Merging + +RFC can be merged only after two Stewards approve it. + +RFC number is assigned before the merge. + +RFC author and two approving Stewards are added to CODEOWNERS file to be +automatically asked to review any future changes to files added or modified +by the RFC. + +## Long-term plan + +IPFS Stewards will adjust the process based on usage patterns. + +## Design rationale + +We want to empower IPFS community and implementers with the ability to propose +changes in a well-known way, without introducing much overhead. + +Guiding principles: +- No new tooling + - Reuse Markdown, Git, and existing PR review process +- Convention over Byzantine process + - Proposing a new RFC should have low cognitive overhead, allowing us to + focus on specs + - Reuse existing Git developer accounts and reputation attached to them + - One should be able to create a valid RFC without reading a long explainer + like this one. Looking at past RFCs, and then copying a template and + opening a PR with their proposal should be more than enough. + +### User benefit + +End users will indirectly benefit from a healthy RFC process being in place: + +- IPFS community members will be able to use RFC drafts for evaluating ideas + before investing time into building new things. +- The bar for creating a brand new IPFS implementation will be lowered, and + existing implementations will be able to propose improvements for others to + adopt. This removes the soft vendor lock-in present when the oldest + implementation is considered as the reference standard and source of truth. +- IPFS Implementers will have a better understanding why certain design + decisions were made, and have both historical context and language-agnostic + specifications with test fixtures ready for use in their project, ensuring + a high level of interoperability. +- More eyes looking at specifications will improve overall quality over time. + +As a result, IPFS will become easier to implement, useful in more contexts, +benefiting more people. + +### Compatibility + +Existing contents of [ipfs/specs][1] repository act as the initial state +against which RFC PRs can be opened. + +### Security + +Existing Git-based review infrastructure, user accounts and reputation +system will be reused. + +Merging RFC will require approval from two IPFS Stewards. + +### Alternatives + +- Maintaining the status quo (no RFC process) is not acceptable, as we want to + move specification discussions away from repositories of specific + implementations. We need a mechanism for discussing improvements that is not + tied to specific implementation or language. +- Creating more elaborate RFC process. This comes with increased overhead and + risk. Introducing a complex process requires deeper understanding of + community needs and pitfalls of preexisting processes, and since we don't + have any process in place, starting light, limits the risk. + +### Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From d868ca5d847cf83f94d0173ba7104160c135fbd0 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 14 Jun 2022 23:26:40 +0200 Subject: [PATCH 02/10] rfc0001: apply suggestions from review Co-authored-by: Mosh <1306020+mishmosh@users.noreply.github.com> --- RFC/0000-template.md | 4 ++-- RFC/0001-lightweight-rfc-process.md | 22 +++++++++++----------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/RFC/0000-template.md b/RFC/0000-template.md index 4bed54750..aa4f8565a 100644 --- a/RFC/0000-template.md +++ b/RFC/0000-template.md @@ -1,7 +1,7 @@ # RFC 0000: Request for Change Template - Start Date: (format: YYYY-MM-DD) @@ -39,7 +39,7 @@ specification compliance. The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. -Provide evidence of consensus within the community, +Provide evidence of rough consensus and working code within the community, and discuss important objections or concerns raised during discussion. ### User benefit diff --git a/RFC/0001-lightweight-rfc-process.md b/RFC/0001-lightweight-rfc-process.md index 744e865be..8a71b6278 100644 --- a/RFC/0001-lightweight-rfc-process.md +++ b/RFC/0001-lightweight-rfc-process.md @@ -6,24 +6,24 @@ # Summary -This Request for Change (RFC) introduces lightweight RFC process -for IPFS specifications [repository][1]. +This Request for Change (RFC) introduces a lightweight RFC process +for the IPFS specifications [repository][1]. [1]: https://github.com/ipfs/specs/ # Motivation -Protocol design discussions often take place in a repository of an IPFS -implementation. Often lacking useful input from IPFS Stewards, other +Today, protocol design discussions often take place in a repository of an IPFS +implementation. These conversations are unintentionally obscured from the useful input of IPFS Stewards, other implementations, service operators and the wider IPFS Community. -IPFS Project needs a mechanism for proposing and evaluating specification +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. # Detailed design -Adopt an informal RFC process for [ipfs/specs][1] repository, providing +Adopt an informal RFC process for the [ipfs/specs][1] repository, providing a minimal structure for opening, reviewing, and merging specification changes. ## Opening @@ -56,7 +56,7 @@ IPFS Stewards will adjust the process based on usage patterns. ## Design rationale -We want to empower IPFS community and implementers with the ability to propose +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: @@ -65,10 +65,10 @@ Guiding principles: - Convention over Byzantine process - Proposing a new RFC should have low cognitive overhead, allowing us to focus on specs - - Reuse existing Git developer accounts and reputation attached to them + - Reuse existing Github developer accounts and reputation attached to them - One should be able to create a valid RFC without reading a long explainer like this one. Looking at past RFCs, and then copying a template and - opening a PR with their proposal should be more than enough. + opening a PR with the proposal should be more than enough. ### User benefit @@ -80,14 +80,14 @@ End users will indirectly benefit from a healthy RFC process being in place: existing implementations will be able to propose improvements for others to adopt. This removes the soft vendor lock-in present when the oldest implementation is considered as the reference standard and source of truth. -- IPFS Implementers will have a better understanding why certain design +- IPFS implementers will have a better understanding of why certain design decisions were made, and have both historical context and language-agnostic specifications with test fixtures ready for use in their project, ensuring a high level of interoperability. - More eyes looking at specifications will improve overall quality over time. As a result, IPFS will become easier to implement, useful in more contexts, -benefiting more people. +and benefit more people. ### Compatibility From 7d5921727b8e9865b8e4d0ef3f3f22f905dbbbbb Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 20 Jun 2022 13:00:00 +0200 Subject: [PATCH 03/10] add specs-stewards Context: https://github.com/ipfs/specs/issues/291 Co-authored-by: Steve Loeppky --- RFC/0001-lightweight-rfc-process.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/RFC/0001-lightweight-rfc-process.md b/RFC/0001-lightweight-rfc-process.md index 8a71b6278..6a4050b79 100644 --- a/RFC/0001-lightweight-rfc-process.md +++ b/RFC/0001-lightweight-rfc-process.md @@ -14,7 +14,7 @@ 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 IPFS Stewards, other +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 @@ -34,25 +34,25 @@ template in `RFC/0000-template.md`. ## Reviewing -IPFS Stewards will review new RFC PRs during weekly triage. +[Specs Stewards] will review new RFC PRs during weekly triage. IPFS Community is encouraged to participate in the review process. -Final decision belongs to IPFS Stewards. +Final decision belongs to [Specs Stewards]. ## Merging -RFC can be merged only after two Stewards approve it. +RFC can be merged only after two [Specs Stewards] approve it. RFC number is assigned before the merge. -RFC author and two approving Stewards are added to CODEOWNERS file to be +RFC 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 RFC. ## Long-term plan -IPFS Stewards will adjust the process based on usage patterns. +[Specs Stewards] will adjust the process based on usage patterns. ## Design rationale @@ -99,7 +99,7 @@ against which RFC PRs can be opened. Existing Git-based review infrastructure, user accounts and reputation system will be reused. -Merging RFC will require approval from two IPFS Stewards. +Merging RFC will require approval from two [Specs Stewards]. ### Alternatives @@ -115,3 +115,5 @@ Merging RFC will require approval from two IPFS Stewards. ### Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +[Specs Stewards]: https://github.com/orgs/ipfs/teams/specs-stewards/members From dbd5149ce7b7207b6ecd42021d96c9ff2e642c09 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 20 Jun 2022 13:29:54 +0200 Subject: [PATCH 04/10] rename RFC to IPIP as suggested in https://github.com/ipfs/specs/pull/289#issuecomment-1156381049 + https://github.com/ipfs/specs/pull/289#issuecomment-1156772388 --- {RFC => IPIP}/0000-template.md | 14 +++---- {RFC => IPIP}/0001-lightweight-rfc-process.md | 41 ++++++++++--------- 2 files changed, 28 insertions(+), 27 deletions(-) rename {RFC => IPIP}/0000-template.md (77%) rename {RFC => IPIP}/0001-lightweight-rfc-process.md (70%) diff --git a/RFC/0000-template.md b/IPIP/0000-template.md similarity index 77% rename from RFC/0000-template.md rename to IPIP/0000-template.md index aa4f8565a..139f0adb2 100644 --- a/RFC/0000-template.md +++ b/IPIP/0000-template.md @@ -1,24 +1,24 @@ -# RFC 0000: Request for Change Template +# IPIP 0000: Request for Change Template - -- Start Date: (format: YYYY-MM-DD) +- Start Date: YYYY-MM-DD - Related Issues: - (add links here) # Summary - -This is the suggested template for new RFCs. + +This is the suggested template for new IPIPs. # Motivation AKA Problem Statement Clearly explain why the existing protocol specification is inadequate -to address the problem that the RFC solves. +to address the problem that the IPIP solves. # Detailed design diff --git a/RFC/0001-lightweight-rfc-process.md b/IPIP/0001-lightweight-rfc-process.md similarity index 70% rename from RFC/0001-lightweight-rfc-process.md rename to IPIP/0001-lightweight-rfc-process.md index 6a4050b79..ad529a0fa 100644 --- a/RFC/0001-lightweight-rfc-process.md +++ b/IPIP/0001-lightweight-rfc-process.md @@ -1,4 +1,4 @@ -# RFC 0001: Lightweight RFC Process for IPFS Specifications +# IPIP 0001: Lightweight "RFC" Process for IPFS Specifications - Start Date: 2022-06-10 - Related Issues: @@ -6,8 +6,9 @@ # Summary -This Request for Change (RFC) introduces a lightweight RFC process -for the IPFS specifications [repository][1]. +This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight +"request for comments/change" process for the IPFS specifications +[repository][1]. [1]: https://github.com/ipfs/specs/ @@ -23,18 +24,18 @@ or implementation of IPFS. # Detailed design -Adopt an informal RFC process for the [ipfs/specs][1] repository, providing a +Adopt an informal IPIP process for the [ipfs/specs][1] repository, providing a minimal structure for opening, reviewing, and merging specification changes. ## Opening Changes to IPFS specifications can be proposed by opening a PR against the repository, and including a short "request for change" document based on the -template in `RFC/0000-template.md`. +template in `IPIP/0000-template.md`. ## Reviewing -[Specs Stewards] will review new RFC PRs during weekly triage. +[Specs Stewards] will review new IPIP PRs during weekly triage. IPFS Community is encouraged to participate in the review process. @@ -42,13 +43,13 @@ Final decision belongs to [Specs Stewards]. ## Merging -RFC can be merged only after two [Specs Stewards] approve it. +IPIP can be merged only after two [Specs Stewards] approve it. -RFC number is assigned before the merge. +IPIP number is assigned before the merge. -RFC 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 RFC. +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. ## Long-term plan @@ -63,18 +64,18 @@ Guiding principles: - No new tooling - Reuse Markdown, Git, and existing PR review process - Convention over Byzantine process - - Proposing a new RFC should have low cognitive overhead, allowing us to + - Proposing a new IPIP should have low cognitive overhead, allowing us to focus on specs - Reuse existing Github developer accounts and reputation attached to them - - One should be able to create a valid RFC without reading a long explainer - like this one. Looking at past RFCs, and then copying a template and + - One should be able to create a valid IPIP without reading a long explainer + like this one. Looking at past IPIPs, and then copying a template and opening a PR with the proposal should be more than enough. ### User benefit -End users will indirectly benefit from a healthy RFC process being in place: +End users will indirectly benefit from a healthy IPIP process being in place: -- IPFS community members will be able to use RFC drafts for evaluating ideas +- IPFS community members will be able to use IPIP drafts for evaluating ideas before investing time into building new things. - The bar for creating a brand new IPFS implementation will be lowered, and existing implementations will be able to propose improvements for others to @@ -92,22 +93,22 @@ and benefit more people. ### Compatibility Existing contents of [ipfs/specs][1] repository act as the initial state -against which RFC PRs can be opened. +against which IPIP PRs can be opened. ### Security Existing Git-based review infrastructure, user accounts and reputation system will be reused. -Merging RFC will require approval from two [Specs Stewards]. +Merging IPIP will require approval from two [Specs Stewards]. ### Alternatives -- Maintaining the status quo (no RFC process) is not acceptable, as we want to +- Maintaining the status quo (no IPIP process) is not acceptable, as we want to move specification discussions away from repositories of specific implementations. We need a mechanism for discussing improvements that is not tied to specific implementation or language. -- Creating more elaborate RFC process. This comes with increased overhead and +- Creating more elaborate IPIP process. This comes with increased overhead and risk. Introducing a complex process requires deeper understanding of community needs and pitfalls of preexisting processes, and since we don't have any process in place, starting light, limits the risk. From d8ee5a17b6a5456b54052ede77ba0410e0ffa794 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 20 Jun 2022 13:52:36 +0200 Subject: [PATCH 05/10] ipip docs: clarify the purpose and life cycle --- IPIP/0000-template.md | 5 ++-- IPIP/0001-lightweight-rfc-process.md | 37 ++++++++++++++++++++-------- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/IPIP/0000-template.md b/IPIP/0000-template.md index 139f0adb2..3fb037b4f 100644 --- a/IPIP/0000-template.md +++ b/IPIP/0000-template.md @@ -1,4 +1,4 @@ -# IPIP 0000: Request for Change Template +# IPIP 0000: InterPlanetary Improvement Proposal Template This is the suggested template for new IPIPs. -# Motivation +## Motivation AKA Problem Statement Clearly explain why the existing protocol specification is inadequate to address the problem that the IPIP solves. -# Detailed design +## Detailed design AKA Solution Proposal diff --git a/IPIP/0001-lightweight-improvement-proposal-process.md b/IPIP/0001-lightweight-improvement-proposal-process.md index c605a3239..64fb28447 100644 --- a/IPIP/0001-lightweight-improvement-proposal-process.md +++ b/IPIP/0001-lightweight-improvement-proposal-process.md @@ -4,7 +4,7 @@ - Related Issues: - [ipfs/specs/issues/286](https://github.com/ipfs/specs/issues/286) -# Summary +## Summary This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight "request for comments/change" process for the IPFS specifications @@ -12,7 +12,7 @@ This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight [1]: https://github.com/ipfs/specs/ -# Motivation +## 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 @@ -22,7 +22,7 @@ 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. -# Detailed design +## Detailed design Adopt an informal IPIP process for the [ipfs/specs][1] repository, providing a minimal structure for opening, reviewing, and merging specification changes. @@ -31,19 +31,19 @@ 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: - - 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.md` would only include - **Motivation** and explainer why certain design decisions were made at a - certain point in time. Initial `IPIP/000N-webdav-gateway.md` would explain - why we added WebDAV spec in the first place. - - If we realize the spec has a bug, we will evaluate the impact: adding more - details, test vectors, and editorials/cosmetics can be fixed without IPIP. - - Things that could cause an interop issues require a PR with fix and IPIP in - `ipfs/specs/IPIP/000M-webdav-fix-for-foo.md` explaining why we make the - breaking spec change, compatibility/migration considerations etc. - -## Opening an improvement proposal (IPIP) +- 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.md` would only include + **Motivation** and explainer why certain design decisions were made at a + certain point in time. Initial `IPIP/000N-webdav-gateway.md` would explain + why we added WebDAV spec in the first place. +- If we realize the spec has a bug, we will evaluate the impact: adding more + details, test vectors, and editorials/cosmetics can be fixed without IPIP. +- Things that could cause an interop issues require a PR with fix and IPIP in + `ipfs/specs/IPIP/000M-webdav-fix-for-foo.md` explaining why we make the + breaking spec change, compatibility/migration considerations etc. + +### Opening an improvement proposal (IPIP) Changes to IPFS specifications can be proposed by opening a Git pull-request (PR) against the `ipfs/specs` repository. @@ -53,7 +53,7 @@ document** based on the template in `ipfs/specs/IPIP/0000-template.md`. When a new specification is added, `ipfs/specs/template.md` can be used. -## Reviewing IPIPs +### Reviewing IPIPs [Specs Stewards] will review new IPIP PRs during periodical (best-effort) triage. @@ -66,7 +66,7 @@ IPIP can be either: The final decision belongs to [Specs Stewards]. -## Merging IPIPs +### Merging IPIPs PR with a IPIP can be merged only after two [Specs Stewards] approve it and there are no objections from other Stewards. @@ -77,7 +77,7 @@ 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. -## Long-term plan +### Long-term plan [Specs Stewards] will adjust the process based on usage patterns. diff --git a/README.md b/README.md index b793746ee..d5957e19f 100644 --- a/README.md +++ b/README.md @@ -2,32 +2,30 @@ > This repository contains the specs for the IPFS Protocol and associated subsystems. -# Table of Contents - -- [IPFS Specifications](#ipfs-specifications) -- [Table of Contents](#table-of-contents) - - [Documentation and Community](#documentation-and-community) - - [Understanding the meaning of the spec badges and their lifecycle](#understanding-the-meaning-of-the-spec-badges-and-their-lifecycle) - - [Index](#index) - - [Contribute](#contribute) - - [InterPlanetary Improvement Process (IPIP)](#interplanetary-improvement-process-ipip) +- [Documentation and Community](#documentation-and-community) +- [Understanding badges](#understanding-the-meaning-of-the-spec-badges-and-their-lifecycle) +- [Index](#index) +- [Contribute](#contribute) + - [InterPlanetary Improvement Process (IPIP)](#interplanetary-improvement-process-ipip) ## Documentation and Community -Looking for user documentation and community support? +Looking for user support? -See https://docs.ipfs.io, https://discuss.ipfs.io/ and https://docs.ipfs.io/community/ instead. +See [Documentation](https://docs.ipfs.io), +[Discussion Forums](https://discuss.ipfs.io/), and other +[Community Resources](https://docs.ipfs.io/community/) instead. ## Understanding the meaning of the spec badges and their lifecycle We use the following label system to identify the state of each spec: -- ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) - A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec. -- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) - A draft that is ready to review. It should be implementable. -- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) - A spec that has been adopted (implemented) and can be used as a reference point to learn how the system works. -- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) - We consider this spec to close to final, it might be improved but the system it specifies should not change fundamentally. -- ![](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) - This spec will not change. -- ![](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) - This spec is no longer in use. +- ![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) - A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec. +- ![draft](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) - A draft that is ready to review. It should be implementable. +- ![reliable](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) - A spec that has been adopted (implemented) and can be used as a reference point to learn how the system works. +- ![stable](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) - We consider this spec to close to final, it might be improved but the system it specifies should not change fundamentally. +- ![permanent](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) - This spec will not change. +- ![deprecated](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) - This spec is no longer in use. Nothing in this spec repository is `permanent` or even `stable` yet. Most of the subsystems are still a `draft` or in `reliable` state. @@ -77,7 +75,7 @@ The specs contained in this and related repositories are: ## Contribute -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) +[![contribute](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) Suggestions, contributions, criticisms are welcome. Though please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows. This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). From b0d6b2c94d6f97f079f084206b5819056b4f021c Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 8 Jul 2022 21:28:05 +0200 Subject: [PATCH 10/10] ipip: add spec template.md https://github.com/ipfs/specs/pull/289#discussion_r901688607 --- ...ightweight-improvement-proposal-process.md | 5 +- template.md | 52 +++++++++++++++++++ 2 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 template.md diff --git a/IPIP/0001-lightweight-improvement-proposal-process.md b/IPIP/0001-lightweight-improvement-proposal-process.md index 64fb28447..0ec678494 100644 --- a/IPIP/0001-lightweight-improvement-proposal-process.md +++ b/IPIP/0001-lightweight-improvement-proposal-process.md @@ -49,9 +49,10 @@ 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`. +document** based on the template in [`ipfs/specs/IPIP/0000-template.md`](./0000-template.md). -When a new specification is added, `ipfs/specs/template.md` can be used. +When a new specification file is added to the repo, it should be based on +the template at [`ipfs/specs/template.md`](../template.md). ### Reviewing IPIPs diff --git a/template.md b/template.md new file mode 100644 index 000000000..f568d21c8 --- /dev/null +++ b/template.md @@ -0,0 +1,52 @@ +# Specification Template + +![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +**Author(s)**: +- Name + +**Maintainer(s)**: +- Name + +* * * + +**Abstract** + +One paragraph explanation of the specification + +## Organization of this document + +- [Introduction](#introduction) +- [Specification](#specification) + - [Test fixtures](#test-fixtures) + - [Security](#security) + - [Privacy and User Control](#privacy-and-user-control) + +## Introduction + +Clearly explain why the specification exists, what is the problem solved here. + +## Specification + +Explain things in depth. + +The resulting specification should be detailed enough to allow competing, +interoperable implementations. + +### Test fixtures + +List relevant CIDs. Describe how implementations can use them to determine +specification compliance. + +### Security + +Explain the security implications/considerations relevant to the spec. + +### Privacy and User Control + +Note if there are any privacy or user control considerations that should be +taken into account by the implementers. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).