From 23f7cc23966bfef4ba463c8283d7c7465e19a9a7 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 8 Jul 2022 20:50:13 +0200 Subject: [PATCH] chore: markdown lint --- IPIP/0000-template.md | 6 +-- ...ightweight-improvement-proposal-process.md | 38 +++++++++---------- README.md | 28 ++++++-------- 3 files changed, 34 insertions(+), 38 deletions(-) diff --git a/IPIP/0000-template.md b/IPIP/0000-template.md index a05a0925c..21ff22ff3 100644 --- a/IPIP/0000-template.md +++ b/IPIP/0000-template.md @@ -8,19 +8,19 @@ submit your IPIP, please use number 0000 and an abbreviated title in the filenam - Related Issues: - (add links here) -# Summary +## Summary 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..e0c27a34d 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,11 @@ > 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 @@ -22,12 +18,12 @@ See https://docs.ipfs.io, https://discuss.ipfs.io/ and https://docs.ipfs.io/comm 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 +73,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).