diff --git a/README.md b/README.md index 204f2d0d..82790891 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,6 @@ **Don't read the specs here! Go to [specs.ipfs.tech](https://specs.ipfs.tech/), it's a much better experience!** -> This repository contains the specs for the IPFS Protocol and associated subsystems. - -- [Documentation and Community](#documentation-and-community) -- [Understanding badges](#understanding-the-meaning-of-the-spec-badges-and-their-lifecycle) -- [Index](#index) -- [Contribute](#contribute) - - [InterPlanetary Improvement Process (IPIP)](#interplanetary-improvement-process-ipip) - ## Documentation and Community Looking for user support? @@ -31,66 +23,26 @@ We use the following label system to identify the state of each spec: Nothing in this spec repository is `permanent` or even `stable` yet. Most of the subsystems are still a `draft` or in `reliable` state. -## Index - -The specs contained in this and related repositories are: - -- **IPFS Protocol:** - - [IPFS Guide](https://docs.ipfs.tech/) - to start your IPFS journey - - [Protocol Architecture Overview (Historical Notes from ~2015)](./ARCHITECTURE.md) - the top-level spec and the stack -- **User Interface (aka Public APIs):** - - [HTTP Gateways](https://specs.ipfs.tech/http-gateways/) - implementation agnostic interfaces for accessing content-addressed data over HTTP - - [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) - implementation agnostic interfaces for content/peer/IPNS routing over HTTP - - IPFS implementations may provide additional HTTP interfaces, for example: - - [Kubo RPC at /api/v0](https://docs.ipfs.tech/reference/kubo/rpc/) -- **Data Formats:** - - [IPLD](https://ipld.io/specs/) - InterPlanetary Linked Data. - - [DAG-CBOR](https://ipld.io/docs/codecs/known/dag-cbor/) - binary format, supporting the complete IPLD Data Model, with excellent performance, and suitable for any job. - - [DAG-JSON](https://ipld.io/docs/codecs/known/dag-json/) - human-readable format, supporting almost the complete IPLD Data Model, and very convenient for interoperability, development, and debugging. - - [DAG-PB](https://ipld.io/docs/codecs/known/dag-pb/) - a binary format for specific limited structures of data, which is highly used in IPFS and [UnixFS](https://specs.ipfs.tech/unixfs/). - - [CAR](https://ipld.io/specs/transport/car/) - transport format used to store content addressable objects in the form of IPLD block data as a sequence of bytes; typically as an [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) file with a `.car` extension - - 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 and Directories:** - - [UnixFS](https://specs.ipfs.tech/unixfs/) - - Related userland concepts (external docs): - - [MFS, Mutable File System, or the Files API](https://docs.ipfs.tech/concepts/file-systems/#mutable-file-system-mfs) -- **Storage Layer:** - - [Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) - - [Repo](https://github.com/ipfs/kubo/blob/master/docs/specifications/repository.md) - Kubo-specific local repository implementation details - - [FileSystem Repo](https://github.com/ipfs/kubo/blob/master/docs/specifications/repository_fs.md) - Kubo-specific filesystem repository implementation -- **Block Exchanges:** - - [Bitswap](https://specs.ipfs.tech/bitswap-protocol/) - BitTorrent-inspired exchange -- **Key Management:** - - [KeyStore](https://github.com/ipfs/kubo/blob/master/docs/specifications/keystore.md) - Kubo-specific key management implementation - - [KeyChain](./KEYCHAIN.md) - Distribution of cryptographic Artifacts -- **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](https://specs.ipfs.tech/ipns/) - InterPlanetary Naming System - - [IPNS Record Creation and Verification](https://specs.ipfs.tech/ipns/ipns-record/) - - [IPNS over PubSub](https://specs.ipfs.tech/ipns/ipns-pubsub-router/) - - [DNSLink](https://dnslink.dev) - mapping DNS names to IPFS content paths - - [DNSAddr](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md) - mapping DNS names to libp2p multiaddrs -- **Other/related/included:** - - [PDD](https://github.com/ipfs/pdd) - Protocol Driven Development - ## Contribute -[![contribute](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) - -Suggestions, contributions, criticisms are welcome. Though please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows. -This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). - -### InterPlanetary Improvement Process (IPIP) - - Want to propose a change to an existing specification? - Or add a new protocol? -See: +This works through the **InterPlanetary Improvement Process (IPIP)**. See: + - [IPIP: Improvement Process for IPFS Specifications](https://specs.ipfs.tech/meta/ipip-process/) - List of [ratified IPIPs](https://specs.ipfs.tech/ipips/) - List of [open IPIPs](https://github.com/ipfs/specs/pulls?q=is%3Apr+is%3Aopen+ipip+sort%3Aupdated-desc) + +If you are wondering how to decide between an issue and an IPIP: + +- **Does Not Need an IPIP**: + - The spec has a bug - something that is plainly a mistake. + - Adding more details, test vectors, and editorials/cosmetic changes. +- **Needs an IPIP**: + - An addition to the protocol that could cause an interop issues. + +[![contribute](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) + +Suggestions, contributions, criticisms are welcome. Though please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows. +This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).