├── 0000-template.md ├── README.md └── proposals ├── 0001-process.md └── 0002-hyper-url.md /0000-template.md: -------------------------------------------------------------------------------- 1 | Title: **HYP-0000: My Proposal** 2 | 3 | Short Name: `0000-my-proposal` 4 | 5 | Type: (Standard, Process, or Informative) 6 | 7 | Status: Undefined (as of YYYY-MM-DD) 8 | 9 | Github PR: (add HTTPS link here after PR is opened) 10 | 11 | Authors: TBD 12 | 13 | 14 | # Summary 15 | [summary]: #summary 16 | 17 | One paragraph explanation of what this is about. 18 | 19 | 20 | # Motivation 21 | [motivation]: #motivation 22 | 23 | Why are we doing this? What use cases does it support? What is the expected outcome? 24 | 25 | 26 | # Usage Documentation 27 | [usage-documentation]: #usage-documentation 28 | 29 | Document new features or processes as if this proposal has already been accepted and implemented. This section should introduce new concepts and terms, describe use cases or situations, and provide examples. If a user-facing feature is added, this should also include user-accessible documentation. 30 | 31 | 32 | # Reference Documentation 33 | [reference-documentation]: #reference-documentation 34 | 35 | This section is a more formal description of the proposal, written as if it was a sub-section of the standard (for technical proposals) or a formal process or "fine print" for process proposals. 36 | 37 | It should be unambiguous and cover all known corner-cases. Formal language (such as protobuf schemas or binary header diagrams) are appropriate here. 38 | 39 | "Standards" proposals should include a section addressing security and privacy implications. 40 | 41 | 42 | # Drawbacks 43 | [drawbacks]: #drawbacks 44 | 45 | Why should we *not* do this? 46 | 47 | 48 | # Rationale and alternatives 49 | [alternatives]: #alternatives 50 | 51 | - Why is this design the best in the space of possible designs? 52 | - What other designs have been considered and what is the rationale for not choosing them? 53 | - What is the impact of not doing this? 54 | 55 | 56 | # Unresolved questions 57 | [unresolved]: #unresolved-questions 58 | 59 | - What parts of the design do you expect to resolve through the HYP consensus process before this gets merged? 60 | - What parts of the design do you expect to resolve through implementation and code review, or are left to independent library or application developers? 61 | - What related issues do you consider out of scope for this HYP that could be addressed in the future independently of the solution that comes out of this HYP? 62 | 63 | 64 | # Changelog 65 | [changelog]: #changelog 66 | 67 | A brief statement about current status can go here, follow by a list of dates 68 | when the status line of this HYP changed (in most-recent-last order). 69 | 70 | - YYYY-MM-DD: First complete draft submitted for review 71 | 72 | 73 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Hypercore Proposals 2 | 3 | This repository contains a series of "HYpercore Proposal" (HYP) 4 | documents, part of the hypercore protocol development and standardization process. 5 | 6 | Proposal documents may be found in the "proposals" folder. 7 | 8 | ## The Process 9 | 10 | TL;DR: write up an HYP markdown file; submit a github PR; revise per review; 11 | community will either accept (merges PR) or not (closes PR). See the ["HYP 12 | Process"][hyp-0001] meta-HYP for details. 13 | 14 | For now this process is as simple and informal; as the number of hypercore developers 15 | and users grows, it may become more formal. Precedents and inspiration include: 16 | 17 | - [Bittorrent Enhancement Proposals (BEP)](http://bittorrent.org/beps/bep_0001.html) 18 | - [Rust RFC Process](https://github.com/rust-lang/rfcs) 19 | - [Python Enhancement Proposal](https://www.python.org/dev/peps/pep-0001/) 20 | 21 | [hyp-0001]: ./proposals/0001-process.md 22 | 23 | ## WG members 24 | 25 | The current HYP Working Group members are: 26 | 27 | - Mathias Buus 28 | 29 | More WG members may be added at the WG's discretion. 30 | 31 | ## Fine Print 32 | 33 | The contents of this repository are all under a CC-BY (Creative Commons 34 | Attribution 4.0) license unless otherwise noted. 35 | 36 | -------------------------------------------------------------------------------- /proposals/0001-process.md: -------------------------------------------------------------------------------- 1 | Title: **HYP-0001: Proposals** 2 | 3 | Short Name: `0001-proposals` 4 | 5 | Type: Standard 6 | 7 | Status: Draft (as of 2020-10-26) 8 | 9 | Github PR: 10 | 11 | Authors: Paul Frazee 12 | 13 | # Summary 14 | [summary]: #summary 15 | 16 | The Hypercore Proposal ("HYP") process is how the Hypercore community reaches consensus around technical protocol enhancements and organizational process. 17 | 18 | # Motivation 19 | [motivation]: #motivation 20 | 21 | The Hypercore protocol is still a living standard. A transparent process is needed for community members to understand what changes are in the pipeline and how new ideas might come to fruition. HYPs are a processes for proposing changes and codifying implementations of the Hypercore Protocol. 22 | 23 | 24 | # How To Submit a Proposal 25 | [submit]: #submit 26 | 27 | As a first step, before drafting a HYP or implementing experimental new 28 | protocol features, it's helpful to informally pitch your idea to see if others 29 | in the community are already thinking something similar, or have discussed the 30 | same idea in the past. This discussion could happen over chat, Github issues, 31 | blog posts, or other channels. If you can recruit collaborators and work out 32 | some of the details, all the better. 33 | 34 | Once your idea has been flushed out, the process for proposing and debating a 35 | new HYP is: 36 | 37 | 1. Use git to fork the [hypercore-protocol/hyp](https://github.com/hypercore-protocol/hyp) 38 | repository 39 | 1. Copy `0000-template.md` to `proposals/0000-my-proposal.md` (don't choose the 40 | "next" number, use zero; `my-proposal` should be a stub identifier for the 41 | proposal.) 42 | 1. Fill in the HYP template. All proposals should have a Type and Status (see 43 | below for details). Feel free to tweak or expand the structure (headers, 44 | content) of the document to fit your needs, but your proposal should be 45 | "complete" before submission. 46 | 1. You can create an informal WIP (work in progress) PR (pull-request) 47 | whenever you like for early feedback and discussion, but there is no 48 | expectation that your proposal will be given detailed review until it is 49 | complete. 50 | 1. When you are ready, submit your complete proposal for review (this could be 51 | opening a PR or removing WIP status from an existing one), with the intent 52 | of being accepted with "Draft" status. 53 | An editor (somebody who is an owner of the HYPs repository) will look over 54 | your proposal for completeness; if acceptable, they will assign one or more 55 | reviewers. 56 | At this stage, two outcomes are the most likely: your proposal 57 | is merged with "Draft" status, or declined. The submitter can withdraw a 58 | proposal at any time. If accepted, an HYp number will be assigned and the PR 59 | merged. If declined, reviewers may give feedback and/or invite proposers to 60 | "significantly revise and resubmit". 61 | 1. While in draft status, proposals can be experimented with. Small corrections 62 | and clarifications can be submitted by PR expect to be merged quickly if 63 | they are reasonable and don't change the broad behavior or semantics of the 64 | proposal; larger changes should be re-submitted as Superseding proposals. 65 | 1. When it seems appropriate, a PR can be submitted to upgrade the status of a 66 | "Draft" to "Active". At this time a final review will take place, with the 67 | outcome being that a proposal stays "Draft" or becomes "Active". 68 | Small changes to the HYP can be included, but it's expected that 69 | this is in broad strokes the same proposal that was reviewed earlier (if 70 | not, a new "Draft" should be proposed that Supersedes). 71 | 1. Small tweaks (grammar, clarifications) to a merged HYP can take place as 72 | regular Github PRs; revisiting or significantly revising should take place 73 | as a new HYP. Draft, Process, and Informational HYPs have a lower bar for 74 | evolution over time via direct PR. 75 | 76 | # Details 77 | [reference-documentation]: #reference-documentation 78 | 79 | ## Types and Statuses 80 | [types]: #types 81 | 82 | HYPs should have a type: 83 | 84 | * **Standard** for technical changes to the protocol, on-disk formats, or 85 | public APIs. These are intended to be *prescriptive*, and to clearly 86 | delineate which features and behaviors are mandatory or optional. 87 | * **Process** for formalizing community processes or other (technical or 88 | non-technical) decisions. For example, a security vulnerability reporting 89 | policy, a process for handling conflicts of interest, or procedures for 90 | mentoring new developers. 91 | * **Informative** for describing conventions, design patterns, existing norms, 92 | special considerations, etc. 93 | 94 | The status of a HYP can be: 95 | 96 | * **Pre-Merge**: a well-formed HYP has been written and a PR opened. The 97 | "Status" line can list Draft when in this state. 98 | * **Draft**: PR has been merged and a number assigned, but additional time is 99 | needed for deeper discussion or more implementation before being "normative" 100 | and expected for implementation. It is acceptable to have "competing" 101 | proposals in this state at the same time. 102 | * **Active**: adopted or intended for implementation in mainline libraries and 103 | clients as appropriate. Again, HYPs should clarify which aspects of 104 | themselves are optional or required for well-behaved clients. 105 | * **Closed**: either consensus was against, a decision was postponed, or the 106 | authors withdrew their proposal. This could apply to any of: a proposal PR 107 | that was never merged, a merged Draft (which was never Active), or an Active 108 | HYP which there is now consensus against without a specific new HYP to 109 | replace it. 110 | * **Superseded**: a formerly Active HYP has been made obsolete by a new 111 | Active HYP; the new HYP should specify specific old HYPs that it would 112 | supersede. 113 | 114 | ## Content and Structure 115 | [content]: #content 116 | 117 | A changelog should be kept in the HYP itself giving the date of any changes of 118 | status. 119 | 120 | A template file is provided, but sections can be added or removed as 121 | appropriate for a specific HYP. 122 | 123 | The HYP text itself should be permissively licensed; the convention is to use 124 | the Creative Commons Attribution License (CC-BY), with attribution to the major 125 | contributing authors listed. 126 | 127 | For appropriate HYPs (including *all* Standards HYPs), authors should 128 | explicitly consider and note impacts on: 129 | 130 | * Privacy and User Rights. Consider reading IETF [RFC 6973] ("Privacy 131 | Considerations for Internet Protocols") and [RFC 8280] ("Research into Human 132 | Rights Protocol Considerations".) 133 | * Backwards compatibility of on-disk archives and older network clients. If a 134 | backwards-incompatible change is proposed, a migration plan should be 135 | sketched out in the proposal. 136 | * Security. 137 | 138 | [RFC-6973]: https://tools.ietf.org/html/rfc6973 139 | [RFC-8280]: https://tools.ietf.org/html/rfc8280 140 | 141 | 142 | ## Acceptance Criteria 143 | [criteria]: #criteria 144 | 145 | The criteria for a proposal being accepted as a Draft are, at a minimum, that 146 | the proposal is complete, understandable, unambiguous, and relevant. There is a 147 | good faith assumption that the submitter believes that the proposal could 148 | actually be adopted and put to beneficial use. An editor may screen proposals 149 | before passing on to the group for review. 150 | 151 | For Standards and Process HYPs, Draft proposals should be specific enough that 152 | they can be prototyped and experimented with (e.g. in a pilot program or test 153 | network), but it isn't expected that all details have been worked out. Working 154 | code is helpful but not required. 155 | 156 | For a Draft to migrate to Active, there is an expectation that the proposal has 157 | been demonstrated (e.g. in working code, though not necessarily in "official" 158 | libraries yet), that the proposal will be the "new normal" and expected 159 | behavior going forward, and that the chance of unforeseen issues arising during 160 | complete adoption is low. 161 | 162 | 163 | ## Decision Making Process 164 | [power]: #power 165 | 166 | There exists a Protocol Working Group (WG) which makes HYP status 167 | decisions; see the Github repository for a list of current members and the 168 | governance process. At time of writing, the WG has only one member, Mathias 169 | Buus, the creator of the Hypercore Protocol. The process outlined here includes 170 | the tools for decision-making as the WG is expanded to include more members. 171 | 172 | By no means should working group members be the only people reviewing or giving 173 | feedback on proposals. 174 | 175 | When deciding on Draft status, at least one WG member must review the entire 176 | proposal in detail, give feedback, and give informed approval. If no detailed 177 | review takes place in the fixed time window, the default is to close (reject) 178 | until a member is willing to commit to review. Any WG member can request 179 | revisions or clarifications (blocking acceptance until addressed), and any 180 | member can block. In other words, consensus requires that at least one member 181 | actively approve, and any member can block, but it isn't required to have every 182 | member review and actively given an opinion. This is referred to as the "loose 183 | consensus" model. 184 | 185 | For Active status, the expectation is that all working group members will 186 | review the proposal and actively participate in consensus. In the event that 187 | not all members can participate, the default is again negative. Any member can 188 | block. This is referred to as the "complete consensus" model. 189 | 190 | For all other status changes, at least one WG member must vouch for or approve 191 | the change ("loose consensus"). If there is unambiguous consensus (or, eg, a 192 | HYP is documenting already adopted practice), a HYP can move directly to Active 193 | status (following the "complete consensus" process). 194 | 195 | In all cases, if there is a deadlock (a block can not be overcome after 196 | further discussion), there is an option to override the block by a vote. The 197 | details of this process are left to description in the Working Group 198 | repository, and are expected to be used only in exceptional cases (eg, are not 199 | invoked by default if a member blocks). 200 | 201 | Proposals are expected to be open for at least three days (72 hours) for 202 | comment (and longer to accommodate special circumstances, like holidays). Vetoes 203 | (blocks) can happen up to a week after initially being submitted for review, 204 | which might be retroactive if the proposal was accepted (by other WG members) 205 | very quickly. 206 | 207 | # Background and References 208 | [references]: #references 209 | 210 | The following standards processes were referenced and considered while 211 | designing the HYP process: 212 | 213 | * **Dat Enhancement Process** as described in [DEP 1][dep-1]. The DEP process 214 | governed changes to the Dat protocol, which was the former name of the 215 | Hypercore Protocol. The HYP process is strongly informed by the DEP process 216 | and takes the bulk of its design from DEP-1. In practice, the DEP struggled 217 | with active participation from WG members over a long period, and was 218 | difficult for core engineers to maintain as large updates were still being 219 | explored and developed for the technology. The HYP process reduces the 220 | initial overhead of DEPs by reducing the initial WG members to one, the 221 | protocol lead, while still allowing for additional WG members to be added. 222 | The goal is to fit the current capacity of the protocol development 223 | participants while still providing a clear pathway for outside contribution 224 | and the provision for expanded governance in the future. It might be 225 | described as "BDFL" governance with a pathway to WG governance. 226 | * **BitTorrent Enhancement Process** as described in [BEP 1][bep-1]. The 227 | Bittorrent protocol has a lot of technical similarities to Hyper, and as a 228 | single protocol family (not a language or full-stack system) is one of the 229 | most similar in scope. The de facto BEP model is that Drafts are very stable 230 | and widely adopted; only the most universal core components are Final. The 231 | HYP process bases it's type categories on the BEP process. There is a single 232 | editor and an explicit BDFL in the BEP process. 233 | * The **[Rust Language RFC Process][rust-rfc]** is relatively new, but has had 234 | a huge volume of proposals, rivaling even the IETF. The process is relatively 235 | lightweight and happens entirely on Github; it is the most similar to the HYP 236 | process proposed here, in terms of Draft/Active distinction. Rust has strong 237 | organizational backing with defined leadership roles; proposals are reviewed 238 | by specific sub-teams. 239 | * **[IETF RFC Process][ietf]**: perhaps the oldest and best known RFC process, 240 | under the motto of "rough consensus and working code". The process is very 241 | bespoke (involving custom file formats and software) and heavy on process 242 | (with working groups and in-person meetings). 243 | * **[XMPP Standards Process][xmpp]**: has the interesting sub-pattern of 244 | regularly updated (annual) standards. XMPP is also a protocol, like 245 | Bittorrent. The protocol was designed for easy extension, and at various 246 | points has seen adoption, extension, and pressure from powerful entities. 247 | * **Python Enhancement Process** documented in [PEP 1][pep-1]. PEPs are 248 | relatively broad in scope (they often speak to process and organizational 249 | dynamics), and are widely cited directly by name. Proposals are usually 250 | debated in great detail on mailing lists before being proposed. Python has a 251 | BDFL (benevolent dictator for life) who has final say over proposals, though 252 | he sometimes delegates to deputies. 253 | * The **W3C** is a paid membership organization which, like the IETF, is made 254 | up of entities large and small, for-profit and altruistic, with decent 255 | regional diversity. W3C standards are often rather large and verbose 256 | documents, and tend to tail (rather than lead) implementation. 257 | 258 | 259 | [dep-1]: https://github.com/datprotocol/DEPs/blob/master/proposals/0001-dep-process.md 260 | [bep-1]: http://bittorrent.org/beps/bep_0001.html 261 | [rust-rfc]: https://github.com/rust-lang/rfcs 262 | [xmpp]: https://xmpp.org/about/standards-process.html 263 | [ietf]: https://www.ietf.org/about/process-docs.html 264 | [pep-1]: https://www.python.org/dev/peps/pep-0001/ 265 | 266 | 267 | # Unresolved questions 268 | [unresolved]: #unresolved-questions 269 | 270 | How mutable should "Draft" Standards HYPs be over time? What about 271 | Informational HYPs? Should there be an additional status ("Living"?) for HYPs 272 | that are expected to evolve, or is this against the whole philosophy of having 273 | specific stable documents to reference? This is expected to be clarified while 274 | this HYP itself is in Draft status. 275 | 276 | Does "Active" status mean that implementation is *mandatory*, and that features 277 | *must* be implemented unless they are explicitly optional? How would this 278 | expectation be enforced for third-party software? This is expected to be 279 | clarified when concrete examples arise. 280 | 281 | 282 | # Changelog 283 | [changelog]: #changelog 284 | 285 | - 2020-10-26: First complete draft submitted provisionally 286 | -------------------------------------------------------------------------------- /proposals/0002-hyper-url.md: -------------------------------------------------------------------------------- 1 | Title: **HYP-0002: hyper:// URL** 2 | 3 | Short Name: `0002-hyper-url` 4 | 5 | Type: Standard 6 | 7 | Status: Draft (as of 2020-05-13) 8 | 9 | Github PR: 10 | 11 | Authors: Paul Frazee 12 | 13 | 14 | # Summary 15 | [summary]: #summary 16 | 17 | The Hypercore Protocol uses a URL format as follows: 18 | 19 | ``` 20 | 'hyper://' hypercore-id [ '+' version-tag ] hier-path [ '?' query ] [ '#' fragment ] 21 | ``` 22 | 23 | These segments are defined as follows: 24 | 25 | - `hypercore-id` An identifier for the Hypercore. Currently a base16-encoded public-key. 26 | - `version-tag` A string identifying a location in the Hypercore log sequence. May be an integer or a 'tag' string which matches the following regex `/[a-z][a-z0-9\.-]*/` (case insensitive). 27 | - `hier-path` The hierarchical path to a resource within the Hypercore, as defined in [RFC 3986 section 3.3](https://tools.ietf.org/html/rfc3986#section-3.3). 28 | - `query` Non-hierarchical data, as defined in [RFC 3986 section 3.4](https://tools.ietf.org/html/rfc3986#section-3.4). 29 | - `fragment` An indirect reference to secondary resources, as defined in [RFC 3986 section 3.5](https://tools.ietf.org/html/rfc3986#section-3.5). 30 | 31 | # Changelog 32 | [changelog]: #changelog 33 | 34 | - 2020-05-13: First complete draft submitted provisionally 35 | --------------------------------------------------------------------------------