From faf3d210d3272508b6291d3e05b91b1c2c3e20ba Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 10 Jul 2019 18:26:00 +0100 Subject: [PATCH 01/18] spec maintainer protocol stub --- SPEC_MAINTAINER_PROTOCOL.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 SPEC_MAINTAINER_PROTOCOL.md diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md new file mode 100644 index 000000000..867c6af77 --- /dev/null +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -0,0 +1,5 @@ +# SPEC MAINTAINER PROTOCOL + +- Specs have editors +- We don't have to list authors nor timestamps on the doc as these are tracked by git +- Specs should be as lean as possible, as explicit as possible From 4f05f5f05adf17bd4a5cbcf943c35a80d839d924 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 10 Jul 2019 18:52:11 +0100 Subject: [PATCH 02/18] reorg things --- public-api/cli/README.md => API_CLI.md | 0 public-api/core/README.md => API_CORE.md | 0 public-api/http/README.md => API_HTTP.md | 0 architecture/README.md => ARCHITECTURE.md | 15 ++-- bitswap/README.md => BITSWAP.md | 42 ++++------ .../README.md => DWEB_ADDRESSING.md | 15 ++-- dex/README.md => IMPORTERS_EXPORTERS.md | 33 +++----- naming/README.md => IPNS.md | 43 ++++------ keychain/README.md => KEYCHAIN.md | 0 keystore/readme.md => KEYSTORE.md | 0 merkledag/README.md => MERKLE_DAG.md | 23 +++--- files/README.md => MUTABLE_FILE_SYSTEM.md | 0 README.md | 77 +++++++++--------- repo/README.md => REPO.md | 0 repo/fs-repo/README.md => REPO_FS.md | 0 unixfs/README.md => UNIXFS.md | 0 .../components/components.001.jpg | Bin .../components/components.002.jpg | Bin .../components/components.003.jpg | Bin .../components/components.004.jpg | Bin .../components/components.005.jpg | Bin .../components/components.key | Bin {dex/graphs => img/dex-graphs}/arch.monopic | Bin {dex/graphs => img/dex-graphs}/arch.txt | 0 {repo/fs-repo => img}/fs-datastore.png | Bin {repo/fs-repo => img}/fs-repo.png | Bin {merkledag => img}/ip.waist.png | Bin {repo => img}/ipfs-repo-contents.png | Bin {repo => img}/ipfs-repo.png | Bin .../ipfs-resolve/ipfs-resolve.gif | Bin .../ipfs-resolve/resolve-gif.001.jpg | Bin .../ipfs-resolve/resolve-gif.002.jpg | Bin .../ipfs-resolve/resolve-gif.003.jpg | Bin .../ipfs-resolve/resolve-gif.004.jpg | Bin .../ipfs-resolve/resolve-gif.005.jpg | Bin .../ipfs-resolve/resolve-gif.006.jpg | Bin .../ipfs-resolve/resolve-gif.007.jpg | Bin .../ipfs-resolve/resolve-gif.008.jpg | Bin {media-artifacts => img}/ipfs-splash-lg.png | Bin {media-artifacts => img}/ipfs-splash.png | Bin architecture/stack.png => img/ipfs-stack.png | Bin {naming => img}/ipns-overview.png | Bin {merkledag => img}/mdag.waist.png | Bin {media-artifacts => img}/spec.key | Bin public-api/README.md | 30 ------- repo/fs-repo/sample-repo/api | 1 - repo/fs-repo/sample-repo/config | 1 - repo/fs-repo/sample-repo/keys/id.pri | 0 repo/fs-repo/sample-repo/keys/id.pub | 0 repo/fs-repo/sample-repo/logs/events | 0 .../logs/events-2015-03-11T13-48-49.562.log | 1 - repo/fs-repo/sample-repo/logs/events.log | 0 repo/fs-repo/sample-repo/repo.lock | 1 - repo/fs-repo/sample-repo/version | 1 - 54 files changed, 106 insertions(+), 177 deletions(-) rename public-api/cli/README.md => API_CLI.md (100%) rename public-api/core/README.md => API_CORE.md (100%) rename public-api/http/README.md => API_HTTP.md (100%) rename architecture/README.md => ARCHITECTURE.md (94%) rename bitswap/README.md => BITSWAP.md (94%) rename dweb-addressing/README.md => DWEB_ADDRESSING.md (61%) rename dex/README.md => IMPORTERS_EXPORTERS.md (90%) rename naming/README.md => IPNS.md (91%) rename keychain/README.md => KEYCHAIN.md (100%) rename keystore/readme.md => KEYSTORE.md (100%) rename merkledag/README.md => MERKLE_DAG.md (97%) rename files/README.md => MUTABLE_FILE_SYSTEM.md (100%) rename repo/README.md => REPO.md (100%) rename repo/fs-repo/README.md => REPO_FS.md (100%) rename unixfs/README.md => UNIXFS.md (100%) rename {media-artifacts => img}/components/components.001.jpg (100%) rename {media-artifacts => img}/components/components.002.jpg (100%) rename {media-artifacts => img}/components/components.003.jpg (100%) rename {media-artifacts => img}/components/components.004.jpg (100%) rename {media-artifacts => img}/components/components.005.jpg (100%) rename {media-artifacts => img}/components/components.key (100%) rename {dex/graphs => img/dex-graphs}/arch.monopic (100%) rename {dex/graphs => img/dex-graphs}/arch.txt (100%) rename {repo/fs-repo => img}/fs-datastore.png (100%) rename {repo/fs-repo => img}/fs-repo.png (100%) rename {merkledag => img}/ip.waist.png (100%) rename {repo => img}/ipfs-repo-contents.png (100%) rename {repo => img}/ipfs-repo.png (100%) rename {media-artifacts => img}/ipfs-resolve/ipfs-resolve.gif (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.001.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.002.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.003.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.004.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.005.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.006.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.007.jpg (100%) rename {media-artifacts => img}/ipfs-resolve/resolve-gif.008.jpg (100%) rename {media-artifacts => img}/ipfs-splash-lg.png (100%) rename {media-artifacts => img}/ipfs-splash.png (100%) rename architecture/stack.png => img/ipfs-stack.png (100%) rename {naming => img}/ipns-overview.png (100%) rename {merkledag => img}/mdag.waist.png (100%) rename {media-artifacts => img}/spec.key (100%) delete mode 100644 public-api/README.md delete mode 100644 repo/fs-repo/sample-repo/api delete mode 100644 repo/fs-repo/sample-repo/config delete mode 100644 repo/fs-repo/sample-repo/keys/id.pri delete mode 100644 repo/fs-repo/sample-repo/keys/id.pub delete mode 100644 repo/fs-repo/sample-repo/logs/events delete mode 100644 repo/fs-repo/sample-repo/logs/events-2015-03-11T13-48-49.562.log delete mode 100644 repo/fs-repo/sample-repo/logs/events.log delete mode 100644 repo/fs-repo/sample-repo/repo.lock delete mode 100644 repo/fs-repo/sample-repo/version diff --git a/public-api/cli/README.md b/API_CLI.md similarity index 100% rename from public-api/cli/README.md rename to API_CLI.md diff --git a/public-api/core/README.md b/API_CORE.md similarity index 100% rename from public-api/core/README.md rename to API_CORE.md diff --git a/public-api/http/README.md b/API_HTTP.md similarity index 100% rename from public-api/http/README.md rename to API_HTTP.md diff --git a/architecture/README.md b/ARCHITECTURE.md similarity index 94% rename from architecture/README.md rename to ARCHITECTURE.md index 3f7b01873..4501ad82f 100644 --- a/architecture/README.md +++ b/ARCHITECTURE.md @@ -1,15 +1,13 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview -==================================================================================================== - -Authors: +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview +Editors: - [Juan Benet](https://github.com/jbenet) - [David Dias](https://github.com/daviddias) -Reviewers: - * * * +**Abstract** + This spec document defines the IPFS protocol stack, the subsystems, the interfaces, and how it all fits together. It delegates non-interface details to other specs as much as possible. This is meant as a top-level view of the protocol and how the system fits together. Note, this document is not meant to be an introduction of the concepts in IPFS and is not recommended as a first pass to understanding how IPFS works. For that, please refer to the [IPFS paper](https://github.com/ipfs/papers/raw/master/ipfs-cap2pfs/ipfs-p2p-file-system.pdf). @@ -81,7 +79,7 @@ IPFS has five layers: - **routing** - locating peers and objects - **network** - establishing connections between peers -![](stack.png) +![](img/ipfs-stack.png) These are briefly described bottom-up. @@ -171,8 +169,7 @@ The IPFS **naming** layer -- or IPNS -- handles the creation of: - mutable pointers to objects - human-readable names -IPNS is based on [SFS](http://en.wikipedia.org/wiki/Self-certifying_File_System). It is a -PKI namespace -- a name is simply the hash of a public key. Whoever controls the private key controls the name. Records are signed by the private key and distributed anywhere (in IPFS, via the routing system). This is an egalitarian way to assign mutable names in the internet at large, without any centralization whatsoever, or certificate authorities. +IPNS is based on [SFS](http://en.wikipedia.org/wiki/Self-certifying_File_System). It is a PKI namespace -- a name is simply the hash of a public key. Whoever controls the private key controls the name. Records are signed by the private key and distributed anywhere (in IPFS, via the routing system). This is an egalitarian way to assign mutable names in the internet at large, without any centralization whatsoever, or certificate authorities. See more in the namin spec (TODO). diff --git a/bitswap/README.md b/BITSWAP.md similarity index 94% rename from bitswap/README.md rename to BITSWAP.md index a0bc4ea0d..a756692ea 100644 --- a/bitswap/README.md +++ b/BITSWAP.md @@ -1,35 +1,25 @@ -# Bitswap +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Bitswap -Authors: +Editors: +- David Dias +- Jeromy Johnson +- Juan Benet - - David Dias - - Jeromy Johnson - - Juan Benet +* * * -Reviewers: - -> tl;dr; - ------ - -# Abstract +**Abstract** Bitswap is the data trading module for IPFS. Its purpose is to request blocks from and send blocks to other peers in the network. Bitswap has two primary jobs: - -1. Attempt to acquire blocks from the network that have been requested by the client. -2. Judiciously (though strategically) send blocks in its possession to other peers who want them. - -# Status of this spec - -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +1. Attempt to acquire blocks from the network that have been requested by the client. +2. Judiciously (though strategically) send blocks in its possession to other peers who want them. # Organization of this document - - [Introduction](#introduction) - - [Subsystems](#subsystems) - - [Implementation Details](#implementation-details) - - [API Spec](#api-spec) - - [Implementations](#implementations) +- [Introduction](#introduction) +- [Subsystems](#subsystems) +- [Implementation Details](#implementation-details) +- [API Spec](#api-spec) +- [Implementations](#implementations) # Introduction @@ -91,7 +81,7 @@ message Message { bytes prefix = 1; // CID prefix (cid version, multicodec and multihash prefix (type + length) bytes data = 2; } - + Wantlist wantlist = 1; optional repeated bytes blocks = 2; // used to send Blocks in bitswap 1.0.0 repeated Block payload = 3; // used to send Blocks in bitswap 1.1.0 @@ -194,7 +184,7 @@ bs.getBlock(multihash, (err, block) => { // 1) try to fetch from repo // 2) if not -> ask bitswap // 2.1) bitswap will cb() once the block is back, once. - // bitswap will write to the repo as well. + // bitswap will write to the repo as well. }) ``` diff --git a/dweb-addressing/README.md b/DWEB_ADDRESSING.md similarity index 61% rename from dweb-addressing/README.md rename to DWEB_ADDRESSING.md index 9877d1129..be0877e92 100644 --- a/dweb-addressing/README.md +++ b/DWEB_ADDRESSING.md @@ -1,9 +1,13 @@ # Addressing on the Decentralized Web +Editors: +- [Lars Gierth](mailto:lgierth@ipfs.io) + +* * * + +**Abstract** > Note: This document is work in progress and largely incomplete. -Authors: -- Lars Gierth \ Table of contents: - Introduction @@ -31,9 +35,6 @@ Table of contents: ## Introduction -Location-based addressing is a centralizing vector on the web. -It lets links rot and drives copies of content into mutual competition. +Location-based addressing is a centralizing vector on the web. It lets links rot and drives copies of content into mutual competition. -This document describes a content-based addressing model -which provides permanent links that don't rot and are cryptographically verifiable. -The result is a more cooperative, resilient, and performant web. +This document describes a content-based addressing model which provides permanent links that don't rot and are cryptographically verifiable. The result is a more cooperative, resilient, and performant web. diff --git a/dex/README.md b/IMPORTERS_EXPORTERS.md similarity index 90% rename from dex/README.md rename to IMPORTERS_EXPORTERS.md index f054e76f2..1f109d3d6 100644 --- a/dex/README.md +++ b/IMPORTERS_EXPORTERS.md @@ -1,23 +1,15 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) DEX -============================================================================= - -Authors: +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Data Importers & Exporters +Editors: - David Dias - Juan Benet -Reviewers: - -- n/a - * * * -# Abstract +**Abstract** IPFS Data Importing spec describes the several importing mechanisms used by IPFS that can be also be reused by other systems. An importing mechanism is composed by one or more chunkers and data format layouts. -# Status of this spec - Lots of discussions around this topic, some of them here: - https://github.com/ipfs/notes/issues/204 @@ -25,22 +17,18 @@ Lots of discussions around this topic, some of them here: - https://github.com/ipfs/notes/issues/205 - https://github.com/ipfs/notes/issues/144 -# Organization of this document - -This RFC is organized by chapters described on the *Table of contents* section. - # Table of contents -- [%N%. Introduction]() -- [%N%. Requirements]() -- [%N%. Architecture]() -- [%N%. Interfaces]() -- [%N%. Implementations]() -- [%N%. References]() +- [Introduction]() +- [Requirements]() +- [Architecture]() +- [Interfaces]() +- [Implementations]() +- [References]() # Introduction -Importing data into IPFS can be done in a variety of ways. These are use-case specific, produce different datastructures, produce different graph topologies, and so on. These are not strictly needed in an IPFS implementation, but definitely make it more useful. +Importing data into IPFS can be done in a variety of ways. These are use-case specific, produce different datastructures, produce different graph topologies, and so on. These are not strictly needed in an IPFS implementation, but definitely make it more useful. These data importing primitivies are really just tools on top of IPLD, meaning that these can be generic and separate from IPFS itself. @@ -114,4 +102,3 @@ These are a set of requirements (or guidelines) of the expectations that need to #### importer # References - diff --git a/naming/README.md b/IPNS.md similarity index 91% rename from naming/README.md rename to IPNS.md index 32c0c56b0..e1b8acae0 100644 --- a/naming/README.md +++ b/IPNS.md @@ -1,36 +1,27 @@ -# IPNS - Inter-Planetary Naming System +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPNS - Inter-Planetary Naming System -Authors: - - - Vasco Santos ([@vasco-santos](https://github.com/vasco-santos)) - -Reviewers: - - - Steven Allen ([@Stebalien](https://github.com/Stebalien)) +Editors: +- Vasco Santos ([@vasco-santos](https://github.com/vasco-santos)) +- Steven Allen ([@Stebalien](https://github.com/Stebalien)) ----- - -# Abstract + +**Abstract** IPFS is powered by content-addressed data, which by nature is immutable: changing an object would change its hash, and consequently its address, making it a different object altogether. However, there are several use cases where we benefit from having mutable data. This is where IPNS gets into the equation. All things considered, the IPFS naming layer is responsible for the creation of: - - - mutable pointers to objects - - human-readable names - -# Status of this spec - -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +- mutable pointers to objects +- human-readable names # Organization of this document - - [Introduction](#introduction) - - [IPNS Record](#ipns-record) - - [Protocol](#protocol) - - [Overview](#overview) - - [API Spec](#api-spec) - - [Integration with IPFS](#integration-with-ipfs) +- [Introduction](#introduction) +- [IPNS Record](#ipns-record) +- [Protocol](#protocol) +- [Overview](#overview) +- [API Spec](#api-spec) +- [Integration with IPFS](#integration-with-ipfs) # Introduction @@ -61,7 +52,7 @@ An IPNS record is a data structure containing the following fields: - Note: The public key **must** be included if it cannot be extracted from the peer ID (reference [libp2p/specs#100](https://github.com/libp2p/specs/pull/100/files)). - 7. **ttl** (uint64) - A hint for how long the record should be cached before going back to, for instance the DHT, in order to check if it has been updated. - + These records are stored locally, as well as spread accross the network, in order to be accessible to everyone. For storing this structured data, we use [Protocol Buffers](https://github.com/google/protobuf), which is a language-neutral, platform neutral extensible mechanism for serializing structured data. ``` @@ -92,9 +83,9 @@ When a node intends to publish a record to the network, an IPNS record needs to As an IPNS record may be updated during its lifetime, a versioning related logic is needed during the publish process. As a consequence, the record must be stored locally, in order to enable the publisher to understand which is the most recent record published. Accordingly, before creating the record, the node must verify if a previous version of the record exists, and update the sequence value for the new record being created. -Once the record is created, it is ready to be spread through the network. This way, a peer can use whatever routing system it supports to make the record accessible to the remaining peers of the network. +Once the record is created, it is ready to be spread through the network. This way, a peer can use whatever routing system it supports to make the record accessible to the remaining peers of the network. -On the other side, each peer must be able to get a record published by another node. It only needs to have the unique identifier used to publish the record to the network. Taking into account the routing system being used, we may obtain a set of occurences of the record from the network. In this case, records can be compared using the sequence number, in order to obtain the most recent one. +On the other side, each peer must be able to get a record published by another node. It only needs to have the unique identifier used to publish the record to the network. Taking into account the routing system being used, we may obtain a set of occurences of the record from the network. In this case, records can be compared using the sequence number, in order to obtain the most recent one. As soon as the node has the most recent record, the signature and the validity must be verified, in order to conclude that the record is still valid and not compromised. diff --git a/keychain/README.md b/KEYCHAIN.md similarity index 100% rename from keychain/README.md rename to KEYCHAIN.md diff --git a/keystore/readme.md b/KEYSTORE.md similarity index 100% rename from keystore/readme.md rename to KEYSTORE.md diff --git a/merkledag/README.md b/MERKLE_DAG.md similarity index 97% rename from merkledag/README.md rename to MERKLE_DAG.md index 7d5802692..3967ea3ac 100644 --- a/merkledag/README.md +++ b/MERKLE_DAG.md @@ -1,16 +1,22 @@ -# The merkledag +# ![](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) The merkledag **This spec has been deprecated in favor of [IPLD](https://github.com/ipld/specs/).** It offers a clearer description of how to link different kinds of hash-based structures (e.g. linking a file in IPFS to a commit in Git), has a more generalized and flexible format, and uses a JSON-compatible representation, among other improvements. -Authors: [Juan Benet](https://github.com/jbenet) - -Reviewers: - +Editors: +- [Juan Benet](https://github.com/jbenet) - [Jeromy Johnson](https://github.com/whyrusleeping) * * * -This is the [Spec](https://github.com/ipfs/specs/) for the IPFS Merkledag. +**Abstract** + +The _ipfs merkledag_ is a directed acyclic graph whose edges are merkle-links. This means that links to objects can authenticate the objects themselves, and that every object contains a secure representation of its children. + +This is a powerful primitive for distributed systems computations. The merkledag simplifies distributed protocols by providing an append-only authenticated datastructure. Parties can communicate and exchange secure references (merkle-links) to objects. The references are enough to verify the correctness of the object at a later time, which allows the objects themselves to be served over untrusted channels. Merkledags also allow the branching of a datastructure and subsequent merging, as in the version control system git. More generally, merkledags simplify the construction of Secure [CRDTs](http://en.wikipedia.org/wiki/Conflict-free_replicated_data_type), which enable distributed, convergent, commutative computation in an authenticated, secure way. + +## Table of Contents + +TODO ## Definitions @@ -26,11 +32,6 @@ This is the [Spec](https://github.com/ipfs/specs/) for the IPFS Merkledag. - `protobuf` - [protocol buffers](https://developers.google.com/protocol-buffers/), a serialization encoding. - `multicodec` - a self-describing, generalized serialization format. -## Abstract - -The _ipfs merkledag_ is a directed acyclic graph whose edges are merkle-links. This means that links to objects can authenticate the objects themselves, and that every object contains a secure representation of its children. - -This is a powerful primitive for distributed systems computations. The merkledag simplifies distributed protocols by providing an append-only authenticated datastructure. Parties can communicate and exchange secure references (merkle-links) to objects. The references are enough to verify the correctness of the object at a later time, which allows the objects themselves to be served over untrusted channels. Merkledags also allow the branching of a datastructure and subsequent merging, as in the version control system git. More generally, merkledags simplify the construction of Secure [CRDTs](http://en.wikipedia.org/wiki/Conflict-free_replicated_data_type), which enable distributed, convergent, commutative computation in an authenticated, secure way. ## The Format diff --git a/files/README.md b/MUTABLE_FILE_SYSTEM.md similarity index 100% rename from files/README.md rename to MUTABLE_FILE_SYSTEM.md diff --git a/README.md b/README.md index 468c450a9..d542c8ebb 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# IPFS Protocol Specifications +# IPFS Specifications [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) @@ -6,61 +6,61 @@ > This repository contains the specs for the IPFS Protocol and associated subsystems. -## Badges and spec lifecycle +## Understanding the meaning of the spec badges 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) - this spec is a work-in-progress, it is likely not even complete. -- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) - this spec is a rough draft and will likely change substantially. -- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) - this spec is believed to be close to final. Minor changes only. -- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) - this spec is likely to improve, but 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-wip-orange.svg?style=flat-square) - A work-in-progress, possibly to describe an idea before actually commiting 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. -Nothing in this spec repository is `permanent` yet. The most important pieces of IPFS are now `reliable` or `stable`. Many subsystems remain as `draft`. Note that, as in many IPFS repositories, most of the work is happening in [the issues](https://github.com/ipfs/specs/issues/) or in [active pull requests](https://github.com/ipfs/specs/pulls/). Go take a look! + +Nothing in this spec repository is `permanent` or even `stable` yet. Most of the subsystems are still a `draft` or in `reliable` state. + +IPFS Specifications are maintained following the [SPEC_MAINTAINER_PROTOCOL](SPEC_MAINTAINER_PROTOCOL.md) ## Index The specs contained in this repository are: - **IPFS Protocol:** - - [protocol](/architecture) - the top-level spec and the stack - - [overviews](/overviews) - quick overviews of the various parts of IPFS + - [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack + - [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS - **User Interface (aka Public APIs):** - - [Core API](/public-api/core) - IPFS programatic interface - - [HTTP API](https://github.com/ipfs/http-api-spec) - IPFS HTTP API specification - - [CLI](/public-api/cli) - Command Line Interface -- **Networking layer:** - - [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: - - network - the network layer spec - - routing - the routing layer spec - - kademlia - Kademlia DHT - - relay - the relay protocol - - dnssd - mDNS for local area networks - - snr - supernode delegated routing - - multirouter - combines multiple others -- **Records, Naming and Record Systems:** - - [IPRS](https://github.com/libp2p/specs/blob/master/IPRS.md) - InterPlanetary Record System - - [IPNS](/naming) - InterPlanetary Naming System -- **Data Structures and formats:** + - [Core API (aka using IPFS as a package/module)](./API_CORE.md) + - [JavaScript implementation details](https://github.com/ipfs/interface-js-ipfs-core) + - [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) + - [CLI (the ipfs daemon API)](./API_CLI.md) + - [HTTP API](./API_HTTP.md) + - HTTP Gateway +- **Data Formats:** - [IPLD](https://github.com/ipld/spec) - InterPlanetary Linked Data. - - [unixfs](/unixfs) - - [multiformats](http://github.com/multiformats/multiformats) + - [Merkle DAG (Deprecated)](./MERKLE_DAG.md) + - Self Describing Formats ([multiformats](http://github.com/multiformats/multiformats)): - [multihash](https://github.com/multiformats/multihash) - self-describing hash digest format. - [multiaddr](https://github.com/multiformats/multiaddr) - self-describing addressing format. - [multicodec](https://github.com/multiformats/multicodec) - self-describing protocol/encoding streams (note: a file is a stream). - [multistream](https://github.com/multiformats/multistream) - multistream is a format -- or simple protocol -- for disambiguating, and layering streams. It is extremely simple. - **Files / Mutable File System:** - - [Files Impl and API](/files) - Virtual File System interface, unix like, on top of the MerkleDAG + - [UnixFS](./UNIXFS.md) + - [Mutable File System (the Files API)](./MUTABLE_FILE_SYSTEM.md) - Virtual File System interface, unix like, on top of the MerkleDAG +- **Storage Layer:** + - Pinning + - [Repo](./REPO.md) - IPFS node local repository spec + - [FileSystem Repo](./REPO_FS.md) - IPFS node local repository spec - **Block Exchanges:** - - [bitswap](/bitswap) - BitTorrent-inspired exchange -- **Specific Internal Components:** - - Blocks and Block Service - - DAG and DAG Service - - Data Importing - - [Repo](/repo) - IPFS node local repository spec + - [Bitswap](./BITSWAP.md) - BitTorrent-inspired exchange - **Key Management:** - - [KeyStore](/keystore) - Key management on IPFS - - [KeyChain](/keychain) - Distribution of cryptographic Artificats + - [KeyStore](./KEYSTORE.md) - Key management on IPFS + - [KeyChain](./KEYCHAIN.md) - Distribution of cryptographic Artificats +- **Networking layer:** + - [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: +- **Records, Naming and Record Systems:** + - [IPNS](./IPNS.md) - InterPlanetary Naming System + - [IPRS](https://github.com/libp2p/specs/blob/master/IPRS.md) - InterPlanetary Record System. A generalization of IPNS for other types of mutable data - **Other/related/included:** - [PDD](https://github.com/ipfs/pdd) - Protocol Driven Development @@ -68,7 +68,4 @@ The specs contained in this repository are: [![](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. -Please be aware that specs are really hard to design by committee. Treat this space like you would the workshop of an artist. Please suggest improvements, but please don't be disappointed if we say no to something. What we leave out is often more important than what we add in. -Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/specs/issues)! This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). diff --git a/repo/README.md b/REPO.md similarity index 100% rename from repo/README.md rename to REPO.md diff --git a/repo/fs-repo/README.md b/REPO_FS.md similarity index 100% rename from repo/fs-repo/README.md rename to REPO_FS.md diff --git a/unixfs/README.md b/UNIXFS.md similarity index 100% rename from unixfs/README.md rename to UNIXFS.md diff --git a/media-artifacts/components/components.001.jpg b/img/components/components.001.jpg similarity index 100% rename from media-artifacts/components/components.001.jpg rename to img/components/components.001.jpg diff --git a/media-artifacts/components/components.002.jpg b/img/components/components.002.jpg similarity index 100% rename from media-artifacts/components/components.002.jpg rename to img/components/components.002.jpg diff --git a/media-artifacts/components/components.003.jpg b/img/components/components.003.jpg similarity index 100% rename from media-artifacts/components/components.003.jpg rename to img/components/components.003.jpg diff --git a/media-artifacts/components/components.004.jpg b/img/components/components.004.jpg similarity index 100% rename from media-artifacts/components/components.004.jpg rename to img/components/components.004.jpg diff --git a/media-artifacts/components/components.005.jpg b/img/components/components.005.jpg similarity index 100% rename from media-artifacts/components/components.005.jpg rename to img/components/components.005.jpg diff --git a/media-artifacts/components/components.key b/img/components/components.key similarity index 100% rename from media-artifacts/components/components.key rename to img/components/components.key diff --git a/dex/graphs/arch.monopic b/img/dex-graphs/arch.monopic similarity index 100% rename from dex/graphs/arch.monopic rename to img/dex-graphs/arch.monopic diff --git a/dex/graphs/arch.txt b/img/dex-graphs/arch.txt similarity index 100% rename from dex/graphs/arch.txt rename to img/dex-graphs/arch.txt diff --git a/repo/fs-repo/fs-datastore.png b/img/fs-datastore.png similarity index 100% rename from repo/fs-repo/fs-datastore.png rename to img/fs-datastore.png diff --git a/repo/fs-repo/fs-repo.png b/img/fs-repo.png similarity index 100% rename from repo/fs-repo/fs-repo.png rename to img/fs-repo.png diff --git a/merkledag/ip.waist.png b/img/ip.waist.png similarity index 100% rename from merkledag/ip.waist.png rename to img/ip.waist.png diff --git a/repo/ipfs-repo-contents.png b/img/ipfs-repo-contents.png similarity index 100% rename from repo/ipfs-repo-contents.png rename to img/ipfs-repo-contents.png diff --git a/repo/ipfs-repo.png b/img/ipfs-repo.png similarity index 100% rename from repo/ipfs-repo.png rename to img/ipfs-repo.png diff --git a/media-artifacts/ipfs-resolve/ipfs-resolve.gif b/img/ipfs-resolve/ipfs-resolve.gif similarity index 100% rename from media-artifacts/ipfs-resolve/ipfs-resolve.gif rename to img/ipfs-resolve/ipfs-resolve.gif diff --git a/media-artifacts/ipfs-resolve/resolve-gif.001.jpg b/img/ipfs-resolve/resolve-gif.001.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.001.jpg rename to img/ipfs-resolve/resolve-gif.001.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.002.jpg b/img/ipfs-resolve/resolve-gif.002.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.002.jpg rename to img/ipfs-resolve/resolve-gif.002.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.003.jpg b/img/ipfs-resolve/resolve-gif.003.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.003.jpg rename to img/ipfs-resolve/resolve-gif.003.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.004.jpg b/img/ipfs-resolve/resolve-gif.004.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.004.jpg rename to img/ipfs-resolve/resolve-gif.004.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.005.jpg b/img/ipfs-resolve/resolve-gif.005.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.005.jpg rename to img/ipfs-resolve/resolve-gif.005.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.006.jpg b/img/ipfs-resolve/resolve-gif.006.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.006.jpg rename to img/ipfs-resolve/resolve-gif.006.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.007.jpg b/img/ipfs-resolve/resolve-gif.007.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.007.jpg rename to img/ipfs-resolve/resolve-gif.007.jpg diff --git a/media-artifacts/ipfs-resolve/resolve-gif.008.jpg b/img/ipfs-resolve/resolve-gif.008.jpg similarity index 100% rename from media-artifacts/ipfs-resolve/resolve-gif.008.jpg rename to img/ipfs-resolve/resolve-gif.008.jpg diff --git a/media-artifacts/ipfs-splash-lg.png b/img/ipfs-splash-lg.png similarity index 100% rename from media-artifacts/ipfs-splash-lg.png rename to img/ipfs-splash-lg.png diff --git a/media-artifacts/ipfs-splash.png b/img/ipfs-splash.png similarity index 100% rename from media-artifacts/ipfs-splash.png rename to img/ipfs-splash.png diff --git a/architecture/stack.png b/img/ipfs-stack.png similarity index 100% rename from architecture/stack.png rename to img/ipfs-stack.png diff --git a/naming/ipns-overview.png b/img/ipns-overview.png similarity index 100% rename from naming/ipns-overview.png rename to img/ipns-overview.png diff --git a/merkledag/mdag.waist.png b/img/mdag.waist.png similarity index 100% rename from merkledag/mdag.waist.png rename to img/mdag.waist.png diff --git a/media-artifacts/spec.key b/img/spec.key similarity index 100% rename from media-artifacts/spec.key rename to img/spec.key diff --git a/public-api/README.md b/public-api/README.md deleted file mode 100644 index c2902c51f..000000000 --- a/public-api/README.md +++ /dev/null @@ -1,30 +0,0 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Public APIs (core + http + cli) -========================================================================================================= - -> This document presents the specifications for the IPFS APIs, namely: 'core', the programmatic interface, 'http', a networked API interface over HTTP and 'cli', the command line interface to interact with IPFS. - -Authors: - -- David Dias - -Reviewers: - -- Jeromy Johnson -- Juan Benet - -# Abstract - -This describes the [IPFS](https://ipfs.io/) APIs, including 'core', 'http' and 'cli'. - -# Organization of this document - -This RFC is organized by chapters described on the *Table of contents* section. Each of the chapters can be found in its own file. - -## API - -- [Core API (aka using IPFS as a package/module)](./core) - - [JavaScript implementation details](https://github.com/ipfs/interface-js-ipfs-core) - - [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) -- [CLI (the ipfs daemon API)](./cli) -- [HTTP API](./http-api) -- [HTTP Gateway](./http-gateway) diff --git a/repo/fs-repo/sample-repo/api b/repo/fs-repo/sample-repo/api deleted file mode 100644 index fd437675a..000000000 --- a/repo/fs-repo/sample-repo/api +++ /dev/null @@ -1 +0,0 @@ -/ip4/127.0.0.1/tcp/5001 diff --git a/repo/fs-repo/sample-repo/config b/repo/fs-repo/sample-repo/config deleted file mode 100644 index 0967ef424..000000000 --- a/repo/fs-repo/sample-repo/config +++ /dev/null @@ -1 +0,0 @@ -{} diff --git a/repo/fs-repo/sample-repo/keys/id.pri b/repo/fs-repo/sample-repo/keys/id.pri deleted file mode 100644 index e69de29bb..000000000 diff --git a/repo/fs-repo/sample-repo/keys/id.pub b/repo/fs-repo/sample-repo/keys/id.pub deleted file mode 100644 index e69de29bb..000000000 diff --git a/repo/fs-repo/sample-repo/logs/events b/repo/fs-repo/sample-repo/logs/events deleted file mode 100644 index e69de29bb..000000000 diff --git a/repo/fs-repo/sample-repo/logs/events-2015-03-11T13-48-49.562.log b/repo/fs-repo/sample-repo/logs/events-2015-03-11T13-48-49.562.log deleted file mode 100644 index 8b1378917..000000000 --- a/repo/fs-repo/sample-repo/logs/events-2015-03-11T13-48-49.562.log +++ /dev/null @@ -1 +0,0 @@ - diff --git a/repo/fs-repo/sample-repo/logs/events.log b/repo/fs-repo/sample-repo/logs/events.log deleted file mode 100644 index e69de29bb..000000000 diff --git a/repo/fs-repo/sample-repo/repo.lock b/repo/fs-repo/sample-repo/repo.lock deleted file mode 100644 index d81cc0710..000000000 --- a/repo/fs-repo/sample-repo/repo.lock +++ /dev/null @@ -1 +0,0 @@ -42 diff --git a/repo/fs-repo/sample-repo/version b/repo/fs-repo/sample-repo/version deleted file mode 100644 index 08c9edff2..000000000 --- a/repo/fs-repo/sample-repo/version +++ /dev/null @@ -1 +0,0 @@ -fs-repo: 1 From 07847781189543bced3eefcd96d94c0b44846259 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 10 Jul 2019 19:17:01 +0100 Subject: [PATCH 03/18] normalize spec files --- API_CLI.md | 16 +++++++++++++--- API_CORE.md | 16 +++++++++++----- API_HTTP.md | 21 ++++++++++++--------- BITSWAP.md | 2 +- DWEB_ADDRESSING.md | 10 +++++----- IMPORTERS_EXPORTERS.md | 14 +++++++------- IPNS.md | 18 +++++++++--------- KEYCHAIN.md | 20 +++++++++----------- KEYSTORE.md | 16 +++++++++++----- MUTABLE_FILE_SYSTEM.md | 25 ++++++------------------- REPO.md | 18 +++++++----------- REPO_FS.md | 26 ++++++++++++++------------ UNIXFS.md | 40 ++++++++++++++++++---------------------- 13 files changed, 123 insertions(+), 119 deletions(-) diff --git a/API_CLI.md b/API_CLI.md index 1f57b4dba..6fd80aaf9 100644 --- a/API_CLI.md +++ b/API_CLI.md @@ -1,7 +1,17 @@ -CLI - Command Line Interface -============================ +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) CLI API, the IPFS Daemon interface -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +**Editors**: +- N/A + +* * * + +**Abstract** + +TODO + +# Table of Contents + +TODO ## Commands diff --git a/API_CORE.md b/API_CORE.md index 2a740e624..f7fc6fbe7 100644 --- a/API_CORE.md +++ b/API_CORE.md @@ -1,9 +1,15 @@ -Core API -======== +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Core API -> The `core` API is the programmatic interface for IPFS, it defines the method signatures. +**Editors**: +- N/A -# Status ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +**Abstract** + +The `core` API is the programmatic interface for IPFS, it defines the method signatures. + +# Table of Contents + +TODo ## Required for compliant IPFS implementation @@ -112,4 +118,4 @@ Core API - put - get -# [Interface definition and test suite](https://github.com/ipfs/interface-ipfs-core) +## [Interface definition and test suite](https://github.com/ipfs/interface-ipfs-core) diff --git a/API_HTTP.md b/API_HTTP.md index 74f279246..3929b6a67 100644 --- a/API_HTTP.md +++ b/API_HTTP.md @@ -1,15 +1,18 @@ -HTTP API -======== +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) HTTP API -# Status +**Editors**: +- N/A -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +* * * -# Interactive HTTP API documentation +**Abstract** -> note: Currently, the HTTP API is a mix between a RPC and RESTful API +TODO -You can find a live version of the HTTP API on Apiary: +# Table of Contents -- Apiary = http://docs.ipfs.apiary.io/# -- Repo - https://github.com/ipfs/http-api-spec +TODO + +## Description + +The current spec is auto generated documentation from the Golang implementation of IPFS. Find it at https://github.com/ipfs/http-api-docs diff --git a/BITSWAP.md b/BITSWAP.md index a756692ea..5cd51eff5 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Bitswap -Editors: +**Editors**: - David Dias - Jeromy Johnson - Juan Benet diff --git a/DWEB_ADDRESSING.md b/DWEB_ADDRESSING.md index be0877e92..f992cc6b4 100644 --- a/DWEB_ADDRESSING.md +++ b/DWEB_ADDRESSING.md @@ -1,15 +1,16 @@ -# Addressing on the Decentralized Web +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Addressing on the Decentralized Web -Editors: +**Editors**: - [Lars Gierth](mailto:lgierth@ipfs.io) * * * **Abstract** -> Note: This document is work in progress and largely incomplete. +This document is largely incomplete. -Table of contents: + +# Table of contents: - Introduction - The precarious web - Link competition and link rot @@ -32,7 +33,6 @@ Table of contents: - Future Work - Related work - ## Introduction Location-based addressing is a centralizing vector on the web. It lets links rot and drives copies of content into mutual competition. diff --git a/IMPORTERS_EXPORTERS.md b/IMPORTERS_EXPORTERS.md index 1f109d3d6..351bdb09c 100644 --- a/IMPORTERS_EXPORTERS.md +++ b/IMPORTERS_EXPORTERS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Data Importers & Exporters -Editors: +**Editors**: - David Dias - Juan Benet @@ -26,7 +26,7 @@ Lots of discussions around this topic, some of them here: - [Implementations]() - [References]() -# Introduction +## Introduction Importing data into IPFS can be done in a variety of ways. These are use-case specific, produce different datastructures, produce different graph topologies, and so on. These are not strictly needed in an IPFS implementation, but definitely make it more useful. @@ -50,7 +50,7 @@ Essentially, data importing is divided into two parts: - Have a set of primitives to digest, chunk and parse files, so that different chunkers can be replaced/added without any trouble. -# Requirements +## Requirements These are a set of requirements (or guidelines) of the expectations that need to be fullfilled for a layout or a splitter: @@ -64,7 +64,7 @@ These are a set of requirements (or guidelines) of the expectations that need to - a splitter, once fed with data, should yield chunks to be added to layout or another layout of itself - an importer is a aggregate of layouts and splitters -# Architecture +## Architecture ```bash ┌───────────┐ ┌──────────┐ @@ -83,7 +83,7 @@ These are a set of requirements (or guidelines) of the expectations that need to - `layouts or topologies` graph topologies (eg balanced vs trickledag vs ext4, ... etc) - `importer` is a process that reads in some data (single file, set of files, archive, db, etc), and outputs a dag. may use many chunkers. may use many layouts. -# Interfaces +## Interfaces #### splitters @@ -91,7 +91,7 @@ These are a set of requirements (or guidelines) of the expectations that need to #### importer -# Implementations +## Implementations #### chunker @@ -101,4 +101,4 @@ These are a set of requirements (or guidelines) of the expectations that need to #### importer -# References +## References diff --git a/IPNS.md b/IPNS.md index e1b8acae0..909dbd7d5 100644 --- a/IPNS.md +++ b/IPNS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPNS - Inter-Planetary Naming System -Editors: +**Editors**: - Vasco Santos ([@vasco-santos](https://github.com/vasco-santos)) - Steven Allen ([@Stebalien](https://github.com/Stebalien)) @@ -14,7 +14,7 @@ All things considered, the IPFS naming layer is responsible for the creation of: - mutable pointers to objects - human-readable names -# Organization of this document +# Table of Contents - [Introduction](#introduction) - [IPNS Record](#ipns-record) @@ -23,13 +23,13 @@ All things considered, the IPFS naming layer is responsible for the creation of: - [API Spec](#api-spec) - [Integration with IPFS](#integration-with-ipfs) -# Introduction +## Introduction Each time a file is modified, its content address changes. As a consequence, the address previously used for getting that file needs to be updated by who is using it. As this is not pratical, IPNS was created to solve the problem. IPNS is based on [SFS](http://en.wikipedia.org/wiki/Self-certifying_File_System). It consists of a PKI namespace, where a name is simply the hash of a public key. As a result, whoever controls the private key has full control over the name. Accordingly, records are signed by the private key and then distributed across the network (in IPFS, via the routing system). This is an egalitarian way to assign mutable names on the Internet at large, without any centralization whatsoever, or certificate authorities. -# IPNS Record +## IPNS Record An IPNS record is a data structure containing the following fields: @@ -75,7 +75,7 @@ message IpnsEntry { } ``` -# Protocol +## Protocol Taking into consideration a p2p network, each peer should be able to publish IPNS records to the network, as well as to resolve the IPNS records published by other peers. @@ -93,18 +93,18 @@ Finally, the network nodes may also republish their records, so that the records ## Overview -![](ipns-overview.png) +![](img/ipns-overview.png) -# API Spec +## API Spec - -# Implementations +## Implementations - - -# Integration with IPFS +## Integration with IPFS #### Local record diff --git a/KEYCHAIN.md b/KEYCHAIN.md index 3345c234c..dfc9e13ab 100644 --- a/KEYCHAIN.md +++ b/KEYCHAIN.md @@ -1,23 +1,21 @@ -# The Keychain +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) The Keychain -Authors: [Juan Benet](github.com/jbenet) - -Reviewers: +**Editors**: +- [Juan Benet](github.com/jbenet) * * * -This is the [Spec](../) for the IPFS Keychain. - -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) - -**THIS WIP IS JUST A NOTES PLACEHOLDER ATM** - -## Abstract +**Abstract** This document presents _The Keychain_, a distributed merkle-linked data structure that links cryptographic keys, identities, signatures, certificates, ciphertexts, proofs, and other objects. The idea of _The Keychain_ is to provide a common construction for managing and distributing cryptographic keys and artifacts. It is similar to a Public Key Infrastructure, but goes further into binding objects together. +# Table of Contents + +TODO + +## Types ```go // Identity represents an entity that can prove possession of keys. diff --git a/KEYSTORE.md b/KEYSTORE.md index 977cc4e8f..dc2674e20 100644 --- a/KEYSTORE.md +++ b/KEYSTORE.md @@ -1,21 +1,27 @@ -# ipfs keystore proposal -Author[s]: [whyrusleeping](github.com/whyrusleeping) +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Keystore -Reviewer[s]: +**Editors:** +- [whyrusleeping](github.com/whyrusleeping) * * * -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) +**Abstract** -Note: This spec is currently in the `wip` phase, things are likely to change very quickly. +TODO + +# Table of Contents + +TODO ## Goals: + To have a secure, simple and user-friendly way of storing and managing keypairs for use by ipfs. As well as the ability to share these keys, encrypt, decrypt, sign and verify data. ## Planned Implementation ### Storage + Keys will be stored in a directory named `keys` under the `$IPFS_PATH` directory. Each named keypair will be stored across two files, the private key in `$NAME` and the public key in `$NAME.pub`. They will be encoded in PEM (or diff --git a/MUTABLE_FILE_SYSTEM.md b/MUTABLE_FILE_SYSTEM.md index 015c93e6b..26e6e1973 100644 --- a/MUTABLE_FILE_SYSTEM.md +++ b/MUTABLE_FILE_SYSTEM.md @@ -1,31 +1,18 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Files (Mutable File System) -==================================================================================================== +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Files (Mutable File System) -Authors: - -- n/a - -Reviewers: - -- n/a +**Editors**: +- N/A * * * # Abstract -`TODO` - -# Organization of this document - -This spec is organized by chapters described on the *Table of contents* section. Each of the chapters can be found in its own file. +TODO # Table of contents -- [1]() -- [2]() -- [...]() +TODO # Implementations -- JavaScript - - Mutable File System - [mfs](https://github.com/ipfs/js-ipfs-mfs) +- JavaScript - Mutable File System - [mfs](https://github.com/ipfs/js-ipfs-mfs) diff --git a/REPO.md b/REPO.md index 369ae3a0c..5b9f626c0 100644 --- a/REPO.md +++ b/REPO.md @@ -1,21 +1,17 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Repo Spec -======================================================================================== - -Authors: +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Repo Spec +Editors: - [Juan Benet](github.com/jbenet) -Reviewer: +* * * -- n/a +**Abstract** -* * * +This spec defines an IPFS Repo, its contents, and its interface. It does not specify how the repo data is actually stored, as that is done via swappable implementations. -The [Spec](../) for IPFS node repositories. +# Table of Contents -This spec defines an IPFS Repo, its contents, and its interface. It does -not specify how the repo data is actually stored, as that is done via -swappable implementations. +TODO ## Definition diff --git a/REPO_FS.md b/REPO_FS.md index f0fb7c3ad..d10dbd777 100644 --- a/REPO_FS.md +++ b/REPO_FS.md @@ -1,13 +1,15 @@ -# IPFS fs-repo version 1 Spec -Author[s]: [Juan Benet](github.com/jbenet) +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) fs-repo + +**Editors**: +- [Juan Benet](github.com/jbenet) -Reviewer[s]: * * * -The [Spec](../../) for the fs-repo IPFS repository. +**Abstract** This spec defines `fs-repo` version `1`, its formats, and semantics. -The repo interface is defined [here](../). + +# Table of Contents ## Definition @@ -26,16 +28,16 @@ The repo interface is defined [here](../). .ipfs/ ├── api <--- running daemon api addr ├── blocks/ <--- objects stored directly on disk -│   └── aa <--- prefix namespacing like git -│      └── aa <--- N tiers +│ └── aa <--- prefix namespacing like git +│ └── aa <--- N tiers ├── config <--- config file (json or toml) ├── hooks/ <--- hook scripts ├── keys/ <--- cryptographic keys -│   ├── id.pri <--- identity private key -│   └── id.pub <--- identity public key +│ ├── id.pri <--- identity private key +│ └── id.pub <--- identity public key ├── datastore/ <--- datastore ├── logs/ <--- 1 or more files (log rotate) -│   └── events.log <--- can be tailed +│ └── events.log <--- can be tailed ├── repo.lock <--- mutex for repo └── version <--- version file ``` @@ -239,9 +241,9 @@ the go-ipfs fs-repo in version 2 uses a different `blocks/` dir layout: ``` /Users/jbenet/.ipfs/blocks ├── 12200007 -│   └── 12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475.data +│ └── 12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475.data ├── 1220000f -│   └── 1220000fadd95a98f3a47c1ba54a26c77e15c1a175a975d88cf198cc505a06295b12.data +│ └── 1220000fadd95a98f3a47c1ba54a26c77e15c1a175a975d88cf198cc505a06295b12.data ``` We MUST address whether we should change the fs-repo spec to match go-ipfs in version 2, or we should change go-ipfs to match the fs-repo spec (more tiers). We MUST also address whether the levels are a repo version parameter or a config parameter. There are filesystems in which a different fanout will have wildly different performance. These are mostly networked and legacy filesystems. diff --git a/UNIXFS.md b/UNIXFS.md index cd5d6e673..753b45036 100644 --- a/UNIXFS.md +++ b/UNIXFS.md @@ -1,12 +1,21 @@ -![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) unixfs -================================================================================ +# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) UnixFS + +**Editors**: +- NA + +* * * + +**Abstract** UnixFS is a [protocol-buffers](https://developers.google.com/protocol-buffers/) based format for describing files, directories, and symlinks in IPFS. The current implementation of UnixFS has grown organically and does not have a clear specification document. See [“implementations”](#implementations) below for reference implementations you can examine to understand the format. Draft work and discussion on a specification for the upcoming version 2 of the UnixFS format is happening in the [`ipfs/unixfs-v2` repo](https://github.com/ipfs/unixfs-v2). Please see the issues there for discussion and PRs for drafts. When the specification is completed there, it will be copied back to this repo and replace this document. +## Table of Contents + +TODO -# Implementations +## Implementations - JavaScript - Data Formats - [unixfs](https://github.com/ipfs/js-ipfs-unixfs) @@ -56,17 +65,11 @@ Importing a file into unixfs is split up into two parts. The first is chunking, ### Chunking -Chunking has two main parameters, chunking strategy and leaf format. +Chunking has two main parameters, chunking strategy and leaf format. -Leaf format should always be set to 'raw', this is mainly configurable for -backwards compatibility with earlier formats that used a Unixfs Data object -with type 'Raw'. Raw leaves means that the nodes output from chunking will be -just raw data from the file with a CID type of 'raw'. +Leaf format should always be set to 'raw', this is mainly configurable for backwards compatibility with earlier formats that used a Unixfs Data object with type 'Raw'. Raw leaves means that the nodes output from chunking will be just raw data from the file with a CID type of 'raw'. -Chunking strategy currently has two different options, 'fixed size' and 'rabin'. -Fixed size chunking will chunk the input data into pieces of a given size. Rabin -chunking will chunk the input data using rabin fingerprinting to determine the -boundaries between chunks. +Chunking strategy currently has two different options, 'fixed size' and 'rabin'. Fixed size chunking will chunk the input data into pieces of a given size. Rabin chunking will chunk the input data using rabin fingerprinting to determine the boundaries between chunks. ### Layout @@ -76,17 +79,10 @@ Layout defines the shape of the tree that gets built from the chunks of the inpu There are currently two options for layout, balanced, and trickle. Additionally, a 'max width' must be specified. The default max width is 174. -The balanced layout creates a balanced tree of width 'max width'. The tree is -formed by taking up to 'max width' chunks from the chunk stream, and creating a -unixfs file node that links to all of them. This is repeated until 'max width' -unixfs file nodes are created, at which point a unixfs file node is created to -hold all of those nodes, recursively. The root node of the resultant tree is returned -as the handle to the newly imported file. +The balanced layout creates a balanced tree of width 'max width'. The tree is formed by taking up to 'max width' chunks from the chunk stream, and creating a unixfs file node that links to all of them. This is repeated until 'max width' unixfs file nodes are created, at which point a unixfs file node is created to hold all of those nodes, recursively. The root node of the resultant tree is returned as the handle to the newly imported file. -If there is only a single chunk, no intermediate unixfs file nodes are created, -and the single chunk is returned as the handle to the file. +If there is only a single chunk, no intermediate unixfs file nodes are created, and the single chunk is returned as the handle to the file. ## Exporting -To read the file data out of the unixfs graph, perform an in order traversal, -emitting the data contained in each of the leaves. +To read the file data out of the unixfs graph, perform an in order traversal, emitting the data contained in each of the leaves. From 2b98c6d794664366d77bf112986f5f2d40b0948c Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 15 Jul 2019 10:47:39 +0100 Subject: [PATCH 04/18] add maintainer protocol --- API_CLI.md | 2 +- API_CORE.md | 2 +- API_HTTP.md | 2 +- ARCHITECTURE.md | 2 +- BITSWAP.md | 2 +- DWEB_ADDRESSING.md | 2 +- IMPORTERS_EXPORTERS.md | 2 +- IPNS.md | 2 +- KEYCHAIN.md | 2 +- KEYSTORE.md | 2 +- MERKLE_DAG.md | 2 +- MUTABLE_FILE_SYSTEM.md | 2 +- REPO.md | 2 +- REPO_FS.md | 4 +- SPEC_MAINTAINER_PROTOCOL.md | 83 +++++++++++++++++++++++++++++++++++-- UNIXFS.md | 2 +- 16 files changed, 95 insertions(+), 20 deletions(-) diff --git a/API_CLI.md b/API_CLI.md index 6fd80aaf9..54b56bf77 100644 --- a/API_CLI.md +++ b/API_CLI.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) CLI API, the IPFS Daemon interface -**Editors**: +**Maintainer(s)**: - N/A * * * diff --git a/API_CORE.md b/API_CORE.md index f7fc6fbe7..d29a4aa16 100644 --- a/API_CORE.md +++ b/API_CORE.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Core API -**Editors**: +**Maintainer(s)**: - N/A **Abstract** diff --git a/API_HTTP.md b/API_HTTP.md index 3929b6a67..297f8e52c 100644 --- a/API_HTTP.md +++ b/API_HTTP.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) HTTP API -**Editors**: +**Maintainer(s)**: - N/A * * * diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4501ad82f..409f1d88a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview -Editors: +**Maintainer(s)**: - [Juan Benet](https://github.com/jbenet) - [David Dias](https://github.com/daviddias) diff --git a/BITSWAP.md b/BITSWAP.md index 5cd51eff5..be221b7ff 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Bitswap -**Editors**: +**Maintainer(s)**: - David Dias - Jeromy Johnson - Juan Benet diff --git a/DWEB_ADDRESSING.md b/DWEB_ADDRESSING.md index f992cc6b4..22ea90833 100644 --- a/DWEB_ADDRESSING.md +++ b/DWEB_ADDRESSING.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Addressing on the Decentralized Web -**Editors**: +**Maintainer(s)**: - [Lars Gierth](mailto:lgierth@ipfs.io) * * * diff --git a/IMPORTERS_EXPORTERS.md b/IMPORTERS_EXPORTERS.md index 351bdb09c..4f0c05828 100644 --- a/IMPORTERS_EXPORTERS.md +++ b/IMPORTERS_EXPORTERS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Data Importers & Exporters -**Editors**: +**Maintainer(s)**: - David Dias - Juan Benet diff --git a/IPNS.md b/IPNS.md index 909dbd7d5..98a48b146 100644 --- a/IPNS.md +++ b/IPNS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPNS - Inter-Planetary Naming System -**Editors**: +**Maintainer(s)**: - Vasco Santos ([@vasco-santos](https://github.com/vasco-santos)) - Steven Allen ([@Stebalien](https://github.com/Stebalien)) diff --git a/KEYCHAIN.md b/KEYCHAIN.md index dfc9e13ab..fc20f3616 100644 --- a/KEYCHAIN.md +++ b/KEYCHAIN.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) The Keychain -**Editors**: +**Maintainer(s)**: - [Juan Benet](github.com/jbenet) * * * diff --git a/KEYSTORE.md b/KEYSTORE.md index dc2674e20..6e5a144d2 100644 --- a/KEYSTORE.md +++ b/KEYSTORE.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Keystore -**Editors:** +**Maintainer(s):** - [whyrusleeping](github.com/whyrusleeping) * * * diff --git a/MERKLE_DAG.md b/MERKLE_DAG.md index 3967ea3ac..5084498a0 100644 --- a/MERKLE_DAG.md +++ b/MERKLE_DAG.md @@ -2,7 +2,7 @@ **This spec has been deprecated in favor of [IPLD](https://github.com/ipld/specs/).** It offers a clearer description of how to link different kinds of hash-based structures (e.g. linking a file in IPFS to a commit in Git), has a more generalized and flexible format, and uses a JSON-compatible representation, among other improvements. -Editors: +**Maintainer(s)**: - [Juan Benet](https://github.com/jbenet) - [Jeromy Johnson](https://github.com/whyrusleeping) diff --git a/MUTABLE_FILE_SYSTEM.md b/MUTABLE_FILE_SYSTEM.md index 26e6e1973..a2e01aa46 100644 --- a/MUTABLE_FILE_SYSTEM.md +++ b/MUTABLE_FILE_SYSTEM.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Files (Mutable File System) -**Editors**: +**Maintainer(s)**: - N/A * * * diff --git a/REPO.md b/REPO.md index 5b9f626c0..45cbf8acc 100644 --- a/REPO.md +++ b/REPO.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Repo Spec -Editors: +**Maintainer(s)**: - [Juan Benet](github.com/jbenet) * * * diff --git a/REPO_FS.md b/REPO_FS.md index d10dbd777..869668fad 100644 --- a/REPO_FS.md +++ b/REPO_FS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) fs-repo -**Editors**: +**Maintainer(s)**: - [Juan Benet](github.com/jbenet) * * * @@ -29,7 +29,7 @@ This spec defines `fs-repo` version `1`, its formats, and semantics. ├── api <--- running daemon api addr ├── blocks/ <--- objects stored directly on disk │ └── aa <--- prefix namespacing like git -│ └── aa <--- N tiers +│ └── aa <--- N tiers ├── config <--- config file (json or toml) ├── hooks/ <--- hook scripts ├── keys/ <--- cryptographic keys diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index 867c6af77..bdf8d2656 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -1,5 +1,80 @@ -# SPEC MAINTAINER PROTOCOL +# Spec Maintainer Protocol -- Specs have editors -- We don't have to list authors nor timestamps on the doc as these are tracked by git -- Specs should be as lean as possible, as explicit as possible +> We have a protocol to maintain specs of protocols! How meta, but very useful. + +## Motivation + +The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to implemented and what users and builders can expect on how it behaves. However, writting specs for a protocol is not novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. + +Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that as much of a pair as possible. This compromises into two main chunks of work: + +- Writting the spec and iterating on it to the point that the spec and the code progress smoothly together. +- For mature and more stable specs, have tests (using [Protocol Driven Development](https://github.com/ipfs/pdd), [TLA+](https://lamport.azurewebsites.net/tla/tla.html) or another framework of verification) to ensure that all implementations stand correct. + +The very aspirational future is to have a spec language in which we can describe how the program should function and it will automatically create the tests to verify it. The aspiration future ++ is having such spec language that writes the code itself and verifies it 🚀. + +The Spec Maintainer Protocol takes a large amount of inspiration from the repo [Lead Maintainer Protocol](https://github.com/ipfs/team-mgmt/blob/master/LEAD_MAINTAINER_PROTOCOL.md). + +## Maintaining a Specification + +A Specification Maintainer is a contributor that has shown that understand the subsystem of the spec that is maintaining and that is passionate about documenting it well. There is a benefit for this contributor to be actively involved with the development of the subsystem at least in one or more of the languages. + +Each spec should be maintained at least by 1 person and up to 3 for efficiency purposes. + +The spec maintainer(s) are recognized at the top of the specification document on the list "Maintainers(s)" and these are the people that should be requested to review a PR to that specific spec. + +### Responsibilities + +As a Spec Maintainer, you are expected to: + +- Respect and follow the [IPFS Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). +- Have a great understanding of the subsystem purpose and how it is used by other parts of the project. +- Review and merge PRs to the Spec +- Respond in a timely manner to Github issues on ipfs/specs repo that are related to the spec being maintained. +- Notify the developers of the subsystem in case there is a new proposal for a change or also request the developers to notify when there is a system change that needs to be reflected on the spec. + +### Specification Status + +The Specification Status description can be found on the main [README of this repo](https://github.com/ipfs/specs#badges-and-spec-lifecycle). + +## Disclaimer as 2019 Q3 + +As of 2019 Q3, the specs are vastly out of date and should not be relied uppon. We will run an effort to get these up to date and check the boxes here when it is done: + +- **IPFS Protocol:** + - [ ] [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack + - [ ] [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS +- **User Interface (aka Public APIs):** + - [ ] [Core API (aka using IPFS as a package/module)](./API_CORE.md) + - [x] [JavaScript implementation details](https://github.com/ipfs/interface-js-ipfs-core) + - [ ] [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) + - [ ] [CLI (the ipfs daemon API)](./API_CLI.md) + - [ ] [HTTP API](./API_HTTP.md) + - HTTP Gateway +- **Data Formats:** + - [ ] [IPLD](https://github.com/ipld/spec) - InterPlanetary Linked Data. + - [x] [Merkle DAG (Deprecated)](./MERKLE_DAG.md) + - [x] Self Describing Formats ([multiformats](http://github.com/multiformats/multiformats)): + - [x] [multihash](https://github.com/multiformats/multihash) - self-describing hash digest format. + - [x] [multiaddr](https://github.com/multiformats/multiaddr) - self-describing addressing format. + - [x] [multicodec](https://github.com/multiformats/multicodec) - self-describing protocol/encoding streams (note: a file is a stream). + - [x] [multistream](https://github.com/multiformats/multistream) - multistream is a format -- or simple protocol -- for disambiguating, and layering streams. It is extremely simple. +- **Files / Mutable File System:** + - [ ] [UnixFS](./UNIXFS.md) + - [ ] [Mutable File System (the Files API)](./MUTABLE_FILE_SYSTEM.md) - Virtual File System interface, unix like, on top of the MerkleDAG +- **Storage Layer:** + - Pinning + - [ ] [Repo](./REPO.md) - IPFS node local repository spec + - [ ] [FileSystem Repo](./REPO_FS.md) - IPFS node local repository spec +- **Block Exchanges:** + - [ ] [Bitswap](./BITSWAP.md) - BitTorrent-inspired exchange +- **Key Management:** + - [ ] [KeyStore](./KEYSTORE.md) - Key management on IPFS + - [ ] [KeyChain](./KEYCHAIN.md) - Distribution of cryptographic Artificats +- **Networking layer:** + - [ ] [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: +- **Records, Naming and Record Systems:** + - [ ] [IPNS](./IPNS.md) - InterPlanetary Naming System + - [ ] [IPRS](https://github.com/libp2p/specs/blob/master/IPRS.md) - InterPlanetary Record System. A generalization of IPNS for other types of mutable data +- **Other/related/included:** + - [ ] [PDD](https://github.com/ipfs/pdd) - Protocol Driven Development diff --git a/UNIXFS.md b/UNIXFS.md index 753b45036..c6bc7930c 100644 --- a/UNIXFS.md +++ b/UNIXFS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) UnixFS -**Editors**: +**Maintainer(s)**: - NA * * * From 5048f4e3b23f4ac15f02fd54d3b4a0ad3e5d587e Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 16 Jul 2019 09:06:02 +0100 Subject: [PATCH 05/18] Update SPEC_MAINTAINER_PROTOCOL.md Co-Authored-By: Adrian Lanzafame --- SPEC_MAINTAINER_PROTOCOL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index bdf8d2656..813a3b015 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -4,7 +4,7 @@ ## Motivation -The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to implemented and what users and builders can expect on how it behaves. However, writting specs for a protocol is not novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. +The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to be implemented and what users and builders can expect on how it behaves. However, writing specs for a protocol is not novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that as much of a pair as possible. This compromises into two main chunks of work: From 8d98475397f033b33468869a2cd9751c9fae06e0 Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 16 Jul 2019 09:06:39 +0100 Subject: [PATCH 06/18] Update SPEC_MAINTAINER_PROTOCOL.md Co-Authored-By: Adrian Lanzafame --- SPEC_MAINTAINER_PROTOCOL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index 813a3b015..d280e5fbf 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -8,7 +8,7 @@ The protocol specifications should be treated as the ultimate source of truth fo Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that as much of a pair as possible. This compromises into two main chunks of work: -- Writting the spec and iterating on it to the point that the spec and the code progress smoothly together. +- Writing the spec and iterating on it to the point that the spec and the code progress smoothly together. - For mature and more stable specs, have tests (using [Protocol Driven Development](https://github.com/ipfs/pdd), [TLA+](https://lamport.azurewebsites.net/tla/tla.html) or another framework of verification) to ensure that all implementations stand correct. The very aspirational future is to have a spec language in which we can describe how the program should function and it will automatically create the tests to verify it. The aspiration future ++ is having such spec language that writes the code itself and verifies it 🚀. From a3e2ae3271c2fd2379cf6e017099fc234fbf7075 Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 16 Jul 2019 09:14:16 +0100 Subject: [PATCH 07/18] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d542c8ebb..1147c9144 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ > This repository contains the specs for the IPFS Protocol and associated subsystems. -## Understanding the meaning of the spec badges +## Understanding the meaning of the spec badges and their lifecycle We use the following label system to identify the state of each spec: From 1afec6043cf574203ab952ed1cdbb813bfc62e86 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:24:41 +0100 Subject: [PATCH 08/18] Update SPEC_MAINTAINER_PROTOCOL.md Co-Authored-By: Alan Shaw --- SPEC_MAINTAINER_PROTOCOL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index d280e5fbf..e1a30ce94 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -4,7 +4,7 @@ ## Motivation -The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to be implemented and what users and builders can expect on how it behaves. However, writing specs for a protocol is not novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. +The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to be implemented and what users and builders can expect on how it behaves. However, writing specs for a protocol is not a novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that as much of a pair as possible. This compromises into two main chunks of work: From 5bd8d668cc05296bd5c261848a872a0976cdedbc Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:25:09 +0100 Subject: [PATCH 09/18] Update SPEC_MAINTAINER_PROTOCOL.md Co-Authored-By: Adrian Lanzafame --- SPEC_MAINTAINER_PROTOCOL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index e1a30ce94..2a7999a50 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -17,7 +17,7 @@ The Spec Maintainer Protocol takes a large amount of inspiration from the repo [ ## Maintaining a Specification -A Specification Maintainer is a contributor that has shown that understand the subsystem of the spec that is maintaining and that is passionate about documenting it well. There is a benefit for this contributor to be actively involved with the development of the subsystem at least in one or more of the languages. +A Specification Maintainer is a contributor that has shown that they understand the subsystem that is maintained by the spec and are passionate about documenting it well. There is a benefit for this contributor to be actively involved with the development of the subsystem at least in one or more of the languages. Each spec should be maintained at least by 1 person and up to 3 for efficiency purposes. From a2dccd2ea33861df04845fbdc8e1fba1f7f69355 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:25:45 +0100 Subject: [PATCH 10/18] Update SPEC_MAINTAINER_PROTOCOL.md Co-Authored-By: Alan Shaw --- SPEC_MAINTAINER_PROTOCOL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index 2a7999a50..8ce5689b4 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -31,7 +31,8 @@ As a Spec Maintainer, you are expected to: - Have a great understanding of the subsystem purpose and how it is used by other parts of the project. - Review and merge PRs to the Spec - Respond in a timely manner to Github issues on ipfs/specs repo that are related to the spec being maintained. -- Notify the developers of the subsystem in case there is a new proposal for a change or also request the developers to notify when there is a system change that needs to be reflected on the spec. +- Notify implementer(s) of the subsystem in case there is a new proposal for a change or also request the implementer(s) to notify when there is a system change that needs to be reflected on the spec. +- Seek review and consensus approval from subsystem implementer(s) to every non-trivial change. ### Specification Status From d8955ca53560fb8e1aa12e35ab3796e8035990e2 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:26:16 +0100 Subject: [PATCH 11/18] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1147c9144..6ae0796a7 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The specs contained in this repository are: - [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS - **User Interface (aka Public APIs):** - [Core API (aka using IPFS as a package/module)](./API_CORE.md) - - [JavaScript implementation details](https://github.com/ipfs/interface-js-ipfs-core) + - [JavaScript Interface](https://github.com/ipfs/interface-js-ipfs-core) - [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) - [CLI (the ipfs daemon API)](./API_CLI.md) - [HTTP API](./API_HTTP.md) From a02eb434925731ec44f19aeacde1e80f5dc2791e Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:26:28 +0100 Subject: [PATCH 12/18] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6ae0796a7..27c641826 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ The specs contained in this repository are: - **User Interface (aka Public APIs):** - [Core API (aka using IPFS as a package/module)](./API_CORE.md) - [JavaScript Interface](https://github.com/ipfs/interface-js-ipfs-core) - - [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) + - [Golang Interface](https://github.com/ipfs/interface-go-ipfs-core) - [CLI (the ipfs daemon API)](./API_CLI.md) - [HTTP API](./API_HTTP.md) - HTTP Gateway From f05eaa9912384a423c33a1f2a266363fe942651f Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:26:41 +0100 Subject: [PATCH 13/18] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 27c641826..dd94f552a 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,6 @@ The specs contained in this repository are: - [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: - **Records, Naming and Record Systems:** - [IPNS](./IPNS.md) - InterPlanetary Naming System - - [IPRS](https://github.com/libp2p/specs/blob/master/IPRS.md) - InterPlanetary Record System. A generalization of IPNS for other types of mutable data - **Other/related/included:** - [PDD](https://github.com/ipfs/pdd) - Protocol Driven Development From c20e8c93fec8a2d59c46bc0f5b635fc3e922f56a Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:26:53 +0100 Subject: [PATCH 14/18] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index dd94f552a..04e17329e 100644 --- a/README.md +++ b/README.md @@ -67,4 +67,5 @@ The specs contained in this repository are: [![](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 15c5fd767aef5504b026bad2ee86e273f4cf84d7 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:28:26 +0100 Subject: [PATCH 15/18] Update REPO_FS.md --- REPO_FS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/REPO_FS.md b/REPO_FS.md index 869668fad..5c3330db3 100644 --- a/REPO_FS.md +++ b/REPO_FS.md @@ -243,7 +243,7 @@ the go-ipfs fs-repo in version 2 uses a different `blocks/` dir layout: ├── 12200007 │ └── 12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475.data ├── 1220000f -│ └── 1220000fadd95a98f3a47c1ba54a26c77e15c1a175a975d88cf198cc505a06295b12.data +│ └── 1220000fadd95a98f3a47c1ba54a26c77e15c1a175a975d88cf198cc505a06295b12.data ``` We MUST address whether we should change the fs-repo spec to match go-ipfs in version 2, or we should change go-ipfs to match the fs-repo spec (more tiers). We MUST also address whether the levels are a repo version parameter or a config parameter. There are filesystems in which a different fanout will have wildly different performance. These are mostly networked and legacy filesystems. From 0d3fb457d93777d8ed9676807d064fdeeb029433 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:28:33 +0100 Subject: [PATCH 16/18] Update REPO_FS.md --- REPO_FS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/REPO_FS.md b/REPO_FS.md index 5c3330db3..ab2f4fa74 100644 --- a/REPO_FS.md +++ b/REPO_FS.md @@ -241,7 +241,7 @@ the go-ipfs fs-repo in version 2 uses a different `blocks/` dir layout: ``` /Users/jbenet/.ipfs/blocks ├── 12200007 -│ └── 12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475.data +│ └── 12200007d4e3a319cd8c7c9979280e150fc5dbaae1ce54e790f84ae5fd3c3c1a0475.data ├── 1220000f │ └── 1220000fadd95a98f3a47c1ba54a26c77e15c1a175a975d88cf198cc505a06295b12.data ``` From e18a60d75ccf4be9f8c744f37f70c51a3d3b5777 Mon Sep 17 00:00:00 2001 From: David Dias Date: Mon, 29 Jul 2019 11:31:32 +0100 Subject: [PATCH 17/18] improve wording --- SPEC_MAINTAINER_PROTOCOL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md index 8ce5689b4..046bcbe6b 100644 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ b/SPEC_MAINTAINER_PROTOCOL.md @@ -6,7 +6,7 @@ The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to be implemented and what users and builders can expect on how it behaves. However, writing specs for a protocol is not a novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. -Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that as much of a pair as possible. This compromises into two main chunks of work: +Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that are matching as much as possible. This compromises into two main chunks of work: - Writing the spec and iterating on it to the point that the spec and the code progress smoothly together. - For mature and more stable specs, have tests (using [Protocol Driven Development](https://github.com/ipfs/pdd), [TLA+](https://lamport.azurewebsites.net/tla/tla.html) or another framework of verification) to ensure that all implementations stand correct. From 1daa09d27b8e91bd671d0e5317bbcc3f83dd65af Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 11 Sep 2019 14:33:42 +0300 Subject: [PATCH 18/18] remove spec maintainer protocol for now --- API_CLI.md | 3 ++ API_CORE.md | 3 ++ API_HTTP.md | 3 ++ ARCHITECTURE.md | 6 ++- BITSWAP.md | 4 +- DWEB_ADDRESSING.md | 5 ++- IMPORTERS_EXPORTERS.md | 2 +- IPNS.md | 2 +- KEYCHAIN.md | 2 +- KEYSTORE.md | 2 +- MERKLE_DAG.md | 2 +- MUTABLE_FILE_SYSTEM.md | 2 +- README.md | 3 -- REPO.md | 2 +- REPO_FS.md | 2 +- SPEC_MAINTAINER_PROTOCOL.md | 81 ------------------------------------- UNIXFS.md | 2 +- 17 files changed, 30 insertions(+), 96 deletions(-) delete mode 100644 SPEC_MAINTAINER_PROTOCOL.md diff --git a/API_CLI.md b/API_CLI.md index 54b56bf77..227d7f7b2 100644 --- a/API_CLI.md +++ b/API_CLI.md @@ -1,5 +1,8 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) CLI API, the IPFS Daemon interface +**Author(s)**: +- N/A + **Maintainer(s)**: - N/A diff --git a/API_CORE.md b/API_CORE.md index d29a4aa16..16e8c36e4 100644 --- a/API_CORE.md +++ b/API_CORE.md @@ -1,5 +1,8 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Core API +**Author(s)**: +- N/A + **Maintainer(s)**: - N/A diff --git a/API_HTTP.md b/API_HTTP.md index 297f8e52c..c673a029b 100644 --- a/API_HTTP.md +++ b/API_HTTP.md @@ -1,5 +1,8 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) HTTP API +**Author(s)**: +- N/A + **Maintainer(s)**: - N/A diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 409f1d88a..a76420805 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,9 +1,13 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview -**Maintainer(s)**: + +**Authors(s)**: - [Juan Benet](https://github.com/jbenet) - [David Dias](https://github.com/daviddias) +**Maintainer(s)**: +- N/A + * * * **Abstract** diff --git a/BITSWAP.md b/BITSWAP.md index be221b7ff..ac8a1be61 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -1,10 +1,12 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Bitswap -**Maintainer(s)**: +**Authors(s)**: - David Dias - Jeromy Johnson - Juan Benet +**Maintainers(s)**: + * * * **Abstract** diff --git a/DWEB_ADDRESSING.md b/DWEB_ADDRESSING.md index 22ea90833..b8fedbd5f 100644 --- a/DWEB_ADDRESSING.md +++ b/DWEB_ADDRESSING.md @@ -1,8 +1,11 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Addressing on the Decentralized Web -**Maintainer(s)**: +**Authors(s)**: - [Lars Gierth](mailto:lgierth@ipfs.io) +**Maintainers(s)**: +- + * * * **Abstract** diff --git a/IMPORTERS_EXPORTERS.md b/IMPORTERS_EXPORTERS.md index 4f0c05828..a2ec7e876 100644 --- a/IMPORTERS_EXPORTERS.md +++ b/IMPORTERS_EXPORTERS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Data Importers & Exporters -**Maintainer(s)**: +**Authors(s)**: - David Dias - Juan Benet diff --git a/IPNS.md b/IPNS.md index 98a48b146..ee8761b44 100644 --- a/IPNS.md +++ b/IPNS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPNS - Inter-Planetary Naming System -**Maintainer(s)**: +**Authors(s)**: - Vasco Santos ([@vasco-santos](https://github.com/vasco-santos)) - Steven Allen ([@Stebalien](https://github.com/Stebalien)) diff --git a/KEYCHAIN.md b/KEYCHAIN.md index fc20f3616..7ea36cef4 100644 --- a/KEYCHAIN.md +++ b/KEYCHAIN.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) The Keychain -**Maintainer(s)**: +**Authors(s)**: - [Juan Benet](github.com/jbenet) * * * diff --git a/KEYSTORE.md b/KEYSTORE.md index 6e5a144d2..1aa451333 100644 --- a/KEYSTORE.md +++ b/KEYSTORE.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Keystore -**Maintainer(s):** +**Authors(s):** - [whyrusleeping](github.com/whyrusleeping) * * * diff --git a/MERKLE_DAG.md b/MERKLE_DAG.md index 5084498a0..db0725ff9 100644 --- a/MERKLE_DAG.md +++ b/MERKLE_DAG.md @@ -2,7 +2,7 @@ **This spec has been deprecated in favor of [IPLD](https://github.com/ipld/specs/).** It offers a clearer description of how to link different kinds of hash-based structures (e.g. linking a file in IPFS to a commit in Git), has a more generalized and flexible format, and uses a JSON-compatible representation, among other improvements. -**Maintainer(s)**: +**Authors(s)**: - [Juan Benet](https://github.com/jbenet) - [Jeromy Johnson](https://github.com/whyrusleeping) diff --git a/MUTABLE_FILE_SYSTEM.md b/MUTABLE_FILE_SYSTEM.md index a2e01aa46..f551e8a52 100644 --- a/MUTABLE_FILE_SYSTEM.md +++ b/MUTABLE_FILE_SYSTEM.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Files (Mutable File System) -**Maintainer(s)**: +**Author(s)**: - N/A * * * diff --git a/README.md b/README.md index 04e17329e..3084a6a92 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,8 @@ We use the following label system to identify the state of each spec: - ![](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. - Nothing in this spec repository is `permanent` or even `stable` yet. Most of the subsystems are still a `draft` or in `reliable` state. -IPFS Specifications are maintained following the [SPEC_MAINTAINER_PROTOCOL](SPEC_MAINTAINER_PROTOCOL.md) - ## Index The specs contained in this repository are: diff --git a/REPO.md b/REPO.md index 45cbf8acc..da657dfac 100644 --- a/REPO.md +++ b/REPO.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Repo Spec -**Maintainer(s)**: +**Author(s)**: - [Juan Benet](github.com/jbenet) * * * diff --git a/REPO_FS.md b/REPO_FS.md index ab2f4fa74..8b5f8cca3 100644 --- a/REPO_FS.md +++ b/REPO_FS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) fs-repo -**Maintainer(s)**: +**Author(s)**: - [Juan Benet](github.com/jbenet) * * * diff --git a/SPEC_MAINTAINER_PROTOCOL.md b/SPEC_MAINTAINER_PROTOCOL.md deleted file mode 100644 index 046bcbe6b..000000000 --- a/SPEC_MAINTAINER_PROTOCOL.md +++ /dev/null @@ -1,81 +0,0 @@ -# Spec Maintainer Protocol - -> We have a protocol to maintain specs of protocols! How meta, but very useful. - -## Motivation - -The protocol specifications should be treated as the ultimate source of truth for how the protocol works, how to be implemented and what users and builders can expect on how it behaves. However, writing specs for a protocol is not a novelty and there has been multiple decades of research on how to do this well, from having a reference implementation, standards bodies and/or formal verification to ensure both code and specs behave the same. It is a hard problem and ultimately one that questions how programming is done as a whole. - -Understanding this, we want to make sure to provide a platform in which the Core Developers and the whole IPFS community can collaborate and build specs and code that are matching as much as possible. This compromises into two main chunks of work: - -- Writing the spec and iterating on it to the point that the spec and the code progress smoothly together. -- For mature and more stable specs, have tests (using [Protocol Driven Development](https://github.com/ipfs/pdd), [TLA+](https://lamport.azurewebsites.net/tla/tla.html) or another framework of verification) to ensure that all implementations stand correct. - -The very aspirational future is to have a spec language in which we can describe how the program should function and it will automatically create the tests to verify it. The aspiration future ++ is having such spec language that writes the code itself and verifies it 🚀. - -The Spec Maintainer Protocol takes a large amount of inspiration from the repo [Lead Maintainer Protocol](https://github.com/ipfs/team-mgmt/blob/master/LEAD_MAINTAINER_PROTOCOL.md). - -## Maintaining a Specification - -A Specification Maintainer is a contributor that has shown that they understand the subsystem that is maintained by the spec and are passionate about documenting it well. There is a benefit for this contributor to be actively involved with the development of the subsystem at least in one or more of the languages. - -Each spec should be maintained at least by 1 person and up to 3 for efficiency purposes. - -The spec maintainer(s) are recognized at the top of the specification document on the list "Maintainers(s)" and these are the people that should be requested to review a PR to that specific spec. - -### Responsibilities - -As a Spec Maintainer, you are expected to: - -- Respect and follow the [IPFS Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). -- Have a great understanding of the subsystem purpose and how it is used by other parts of the project. -- Review and merge PRs to the Spec -- Respond in a timely manner to Github issues on ipfs/specs repo that are related to the spec being maintained. -- Notify implementer(s) of the subsystem in case there is a new proposal for a change or also request the implementer(s) to notify when there is a system change that needs to be reflected on the spec. -- Seek review and consensus approval from subsystem implementer(s) to every non-trivial change. - -### Specification Status - -The Specification Status description can be found on the main [README of this repo](https://github.com/ipfs/specs#badges-and-spec-lifecycle). - -## Disclaimer as 2019 Q3 - -As of 2019 Q3, the specs are vastly out of date and should not be relied uppon. We will run an effort to get these up to date and check the boxes here when it is done: - -- **IPFS Protocol:** - - [ ] [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack - - [ ] [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS -- **User Interface (aka Public APIs):** - - [ ] [Core API (aka using IPFS as a package/module)](./API_CORE.md) - - [x] [JavaScript implementation details](https://github.com/ipfs/interface-js-ipfs-core) - - [ ] [Golang implementation details](https://github.com/ipfs/interface-go-ipfs-core) - - [ ] [CLI (the ipfs daemon API)](./API_CLI.md) - - [ ] [HTTP API](./API_HTTP.md) - - HTTP Gateway -- **Data Formats:** - - [ ] [IPLD](https://github.com/ipld/spec) - InterPlanetary Linked Data. - - [x] [Merkle DAG (Deprecated)](./MERKLE_DAG.md) - - [x] Self Describing Formats ([multiformats](http://github.com/multiformats/multiformats)): - - [x] [multihash](https://github.com/multiformats/multihash) - self-describing hash digest format. - - [x] [multiaddr](https://github.com/multiformats/multiaddr) - self-describing addressing format. - - [x] [multicodec](https://github.com/multiformats/multicodec) - self-describing protocol/encoding streams (note: a file is a stream). - - [x] [multistream](https://github.com/multiformats/multistream) - multistream is a format -- or simple protocol -- for disambiguating, and layering streams. It is extremely simple. -- **Files / Mutable File System:** - - [ ] [UnixFS](./UNIXFS.md) - - [ ] [Mutable File System (the Files API)](./MUTABLE_FILE_SYSTEM.md) - Virtual File System interface, unix like, on top of the MerkleDAG -- **Storage Layer:** - - Pinning - - [ ] [Repo](./REPO.md) - IPFS node local repository spec - - [ ] [FileSystem Repo](./REPO_FS.md) - IPFS node local repository spec -- **Block Exchanges:** - - [ ] [Bitswap](./BITSWAP.md) - BitTorrent-inspired exchange -- **Key Management:** - - [ ] [KeyStore](./KEYSTORE.md) - Key management on IPFS - - [ ] [KeyChain](./KEYCHAIN.md) - Distribution of cryptographic Artificats -- **Networking layer:** - - [ ] [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers: -- **Records, Naming and Record Systems:** - - [ ] [IPNS](./IPNS.md) - InterPlanetary Naming System - - [ ] [IPRS](https://github.com/libp2p/specs/blob/master/IPRS.md) - InterPlanetary Record System. A generalization of IPNS for other types of mutable data -- **Other/related/included:** - - [ ] [PDD](https://github.com/ipfs/pdd) - Protocol Driven Development diff --git a/UNIXFS.md b/UNIXFS.md index c6bc7930c..4a071d8a4 100644 --- a/UNIXFS.md +++ b/UNIXFS.md @@ -1,6 +1,6 @@ # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) UnixFS -**Maintainer(s)**: +**Author(s)**: - NA * * *