Merge pull request #214 from ipfs/specs-maintainer-protocol

Repo reorg, cleaning up the spider webs

Author: Stebalien

public-api/cli/README.md renamed to API_CLI.md

@@ -1,7 +1,20 @@
-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)
+**Author(s)**:
+- N/A
+
+**Maintainer(s)**:
+- N/A
+
+* * *
+
+**Abstract**
+
+TODO
+
+# Table of Contents
+
+TODO
 
 ## Commands
 

public-api/core/README.md renamed to API_CORE.md

@@ -1,9 +1,18 @@
-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.
+**Author(s)**:
+- N/A
 
-# Status ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
+**Maintainer(s)**:
+- N/A
+
+**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 +121,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)

API_HTTP.md

@@ -0,0 +1,21 @@
+# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) HTTP API
+
+**Author(s)**:
+- N/A
+
+**Maintainer(s)**:
+- N/A
+
+* * *
+
+**Abstract**
+
+TODO
+
+# Table of Contents
+
+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

architecture/README.md renamed to ARCHITECTURE.md

@@ -1,15 +1,17 @@
-![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview
-====================================================================================================
+# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview
 
-Authors:
 
+**Authors(s)**:
 - [Juan Benet](https://github.com/jbenet)
 - [David Dias](https://github.com/daviddias)
 
-Reviewers:
+**Maintainer(s)**:
+- N/A
 
 * * *
 
+**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 +83,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 +173,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).
 

bitswap/README.md renamed to BITSWAP.md

@@ -1,35 +1,27 @@
-# Bitswap
+# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Bitswap
 
-Authors:
+**Authors(s)**:
+- David Dias
+- Jeromy Johnson
+- Juan Benet
 
-  - David Dias
-  - Jeromy Johnson
-  - Juan Benet
+**Maintainers(s)**:
 
-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 +83,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 +186,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.
 })
 ```
 

DWEB_ADDRESSING.md

@@ -0,0 +1,43 @@
+# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Addressing on the Decentralized Web
+
+**Authors(s)**:
+- [Lars Gierth](mailto:[email protected])
+
+**Maintainers(s)**:
+-
+
+* * *
+
+**Abstract**
+
+This document is largely incomplete.
+
+
+# Table of contents:
+- Introduction
+- The precarious web
+  - Link competition and link rot
+  - The addressing rift
+- DWeb Addressing
+- Namespaces
+  - /ipfs -- immutable data
+  - /ipns -- mutable pointers
+  - Addressing data from other content-addressed systems
+  - Network addressing
+- Interoperability
+  - DWeb Addressing with HTTP
+  - ipfs:// and ipns:// URL schemes
+  - dweb: URI scheme
+  - Content Security Policy / Origins
+- Appendix
+  - DWeb Maturity Model
+  - FAQ
+  - Implementations
+  - 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.
+
+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.

dex/README.md renamed to IMPORTERS_EXPORTERS.md

@@ -1,46 +1,34 @@
-![](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
 
+**Authors(s)**:
 - 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
 - https://github.com/ipfs/notes/issues/216
 - 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
+## 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.
 
@@ -62,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:
 
@@ -76,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
               ┌───────────┐        ┌──────────┐
@@ -95,15 +83,15 @@ 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
 
 #### layout
 
 #### importer
 
-# Implementations
+## Implementations
 
 #### chunker
 
@@ -113,5 +101,4 @@ These are a set of requirements (or guidelines) of the expectations that need to
 
 #### importer
 
-# References
-
+## References