Add versioning to RFCs (#206)

Update publish process for versioning
Added CONTRIBUTING.md
Update publishing scripts to version drafts
Update CircleCI config
Update template to include permalink

0001-interledger-architecture/0001-interledger-architecture.md

@@ -1,3 +1,7 @@
+---
+title: Interledger Architecture
+draft: 1
+---
 # Interledger Architecture
 
 Interledger provides for secure payments across multiple assets on different ledgers. The architecture consists of a conceptual model for interledger payments, a mechanism for securing payments, and a suite of protocols that implement this design.

0002-crypto-conditions/0002-crypto-conditions.md

@@ -1 +1,4 @@
+---
+deprecated: true
+---
 Spec has been moved to https://github.com/rfcs/crypto-conditions/

0003-interledger-protocol/0003-interledger-protocol.md

@@ -1,3 +1,7 @@
+---
+title: The Interledger Protocol (ILP)
+draft: 1
+---
 # Interledger Protocol (ILP)
 
 ## Preface

0004-ledger-plugin-interface/0004-ledger-plugin-interface.md

@@ -1,4 +1,8 @@
-# Ledger Plugin Interface (Javascript)
+---
+title: The Javascript Ledger Plugin Interface
+draft: 1
+---
+# Javascript Ledger Plugin Interface
 
 The Interledger Protocol is a protocol suite for connecting blockchains and other ledgers.
 

0005-optimistic-transport-protocol/0005-optimistic-transport-protocol.md

@@ -1 +1,4 @@
+---
+deprecated: true
+---
 **What was formerly known as the "Optimistic Transport Protocol" has been removed from the standard Interledger Protocol stack.**

0006-universal-transport-protocol/0006-universal-transport-protocol.md

@@ -1 +1,4 @@
+---
+deprecated: true
+---
 **What was formerly known as the "Universal Transport Protocol" has been merged into the [Interledger Protocol](../0003-interledger-protocol).**

0007-atomic-transport-protocol/0007-atomic-transport-protocol.md

@@ -1,3 +1,6 @@
+---
+deprecated: true
+---
 **What was formerly known as the "Atomic Transport Protocol" has been removed from the standard Interledger Protocol stack.**
 
 The Atomic mode outlined in the Interledger whitepaper may be used within segments of an Interledger payment path amongst groups of connectors and ledgers that support the required functionality. In an open system of interconnected ledgers, it seems unlikely that all parties in a payment path would have commonly trusted entities between them that could serve as notaries. The protocols used within specific groups need not be standardized because the failure to select commonly trusted notaries would prevent interoperability anyway.

0008-interledger-quoting-protocol/0008-interledger-quoting-protocol.md

@@ -1,3 +1,7 @@
+---
+title: The Interledger Quoting Protocol (ILQP)
+draft: 1
+---
 # Interledger Quoting Protocol (ILQP)
 
 The Interledger Quoting Protocol is a method of getting quote information from a Connector in preparation for arranging transfers across two ledgers. The quote returned by a Connector is non-binding, but provides a basis for choosing which connectors to use.

0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md

@@ -1,3 +1,7 @@
+---
+title: The Simple Payment Setup Protocol (SPSP)
+draft: 1
+---
 # Simple Payment Setup Protocol (SPSP)
 
 ## Preface

0010-connector-to-connector-protocol/0010-connector-to-connector-protocol.md

@@ -1,3 +1,7 @@
+---
+title: The Connector to Connector protocol
+draft: 1
+---
 # Connector to Connector protocol
 
 ## Discovery

0011-interledger-payment-request/0011-interledger-payment-request.md

@@ -1,3 +1,7 @@
+---
+title: Interledger Payment Requests (IPR)
+draft: 1
+---
 # Interledger Payment Request (IPR)
 
 The Interledger Payment Request (IPR) transport protocol is an end-to-end protocol in which the receiver of an Interledger payment first communicates a request for payment to the sender. This document also recommends a method for receivers to generate payment requests such that they can verify incoming payments without storing all outstanding requests.

0015-ilp-addresses/0015-ilp-addresses.md

@@ -1,4 +1,8 @@
-# ILP Addresses
+---
+title: ILP Addresses
+draft: 1
+---
+# ILP Addresses - v1.0.0
 
 _ILP addresses_ provide a way to [route](#routing) payments to their intended destination through a recursive series of hops, including any number of ILP Connectors. (This happens after the payment is set up on by a higher-level payment setup protocol such as [SPSP](../0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md).) Addresses are not meant to be user-facing, but allow several ASCII characters for easy debugging.
 

0016-pre-shared-key/0016-pre-shared-key.md

@@ -1,4 +1,8 @@
-# Pre-Shared Key Transport Protocol
+---
+title: The Pre-Shared Key Transport Protocol (PSK)
+draft: 1
+---
+# Pre-Shared Key Transport Protocol (PSK)
 
 The Pre-Shared Key (PSK) protocol is an end-to-end transport protocol, used by the sender and receiver of an ILP payment to decide on a condition and fulfillment for a payment. By default, the protocol also encrypts any additional data sent along with the payment, using [AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode). The full ILP payment is authenticated through an [HMAC-SHA-256](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) which is used to generate the fulfillment of a PSK payment. The entirety of the PSK data, including public headers, encrypted private headers, and encrypted private data, is encoded into an octet-stream that forms the data portion of the [ILP Packet](https://github.com/interledger/rfcs/blob/master/0003-interledger-protocol/0003-interledger-protocol.md). The PSK data is authenticated via AES-256-GCM in addition to the HMAC-SHA-256 which authenticates the full ILP payment.
 

0017-ledger-requirements/0017-ledger-requirements.md

@@ -1,3 +1,7 @@
+---
+title: Ledger Layer Requirements
+draft: 1
+---
 # Ledger Layer Requirements
 
 ## Introduction

0018-connector-risk-mitigations/0018-connector-risk-mitigations.md

@@ -1,3 +1,7 @@
+---
+title: Connector Risk Mitigations
+draft: 1
+---
 # Connector Risk Mitigations
 
 Interledger connectors take some risk in exchange for the revenue they generate from facilitating payments. This document outlines the major categories of risks connectors face and suggests some possible mitigations.

0019-glossary/0019-glossary.md

@@ -1,3 +1,7 @@
+---
+title: Glossary
+draft: 1
+---
 # Glossary
 
 ## Account

0020-explain-like-im-five/0020-explain-like-im-five.md

@@ -1,3 +1,7 @@
+---
+title: Interledger Protocol - Explain Like I'm Five (ELI5)
+draft: 1
+---
 ## Interledger Protocol: Explain Like I'm Five (ELI5)
 
 ### Introduction

0021-plugin-rpc-api/0021-plugin-rpc-api.md

@@ -1,3 +1,7 @@
+---
+title: Plugin RPC API
+draft: 1
+---
 # Plugin RPC API
 
 ## Description

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# CONTRIBUTING
+
+Contributions to the Interledger RFC repo follow the following document publishing process.
+
+## Background
+
+The work of the Interledger community is being done under the framework of a W3C Community Group and is therefor guided by the [processes](https://www.w3.org/community/about/agreements/) laid out by the W3C for these groups.
+
+Also influencing this process is the well-established and popular IETF RFC process. 
+
+## Process
+
+The ILP RFC process attempts to be easy to use but also rigorous enough that there are permalinks to revisions of documents for reference purposes.
+
+The process differentiates between specifications that are incubating (similar to IETF Internet Drafts) and those that are mature (similar to IETF RFCs).
+
+The two document types are *Working Drafts* and *Candidate Specifications*.
+
+1. When a community member wishes to submit a new document for comment they will submit a Pull Request to the [RFCs repo](https://github.com/interledger/rfcs/) which adds a new Markdown file. The file MUST follow the naming convention `0000-title`, where title is a lower case title with spaces replaced by hyphens (`-`), and have front-matter (similar to GitHub pages rendered from MarkDown) specifying at least a `title` and `draft` (an integer, starting at 1 and incrmenting with each revision of the RFC).
+
+Example:
+```
+---
+title: The Interledger Architecture
+draft: 1
+---
+# Interledger Architecture
+
+Lorum Ipsum etc
+```
+
+2. One of the project maintainers will review the submission and assign an RFC number to the document, making a follow up commit to the PR which renames the file and folder as appropriate.
+
+3. Subsequent updates to the document will trigger a publishing workflow that creates an HTML rendered version of the document that contains a permalink to the draft. Each revision must increment the `draft` number in the front-matter or the publishing will fail. 
+
+4. These Interledger RFCs are living documents that start as Working Drafts and are iterated on until they are considered stable.
+
+5. *Working Drafts* have an RFC number AND a draft number starting at 1 and increasing by 1 each time the content is changed.
+
+6. When a Working Draft is considered stable there is a call for review from the community to publish the document as a *Candidate Specification*.
+
+7. Assuming there is consensus to publish, the document becomes a *Candidate Specification* and no further substantive changes are allowed under the same RFC number. (The draft number changes to `FINAL`).
+
+8. *Candidate Specifications* will also be published as W3C Community Group reports and may be published as IETF Internet Drafts if appropriate.
+
+9. A different template is used for *Working Drafts* and *Candidate Specifications* to help readers differentiate between them.

README.md

@@ -5,6 +5,8 @@
 
 This repository contains a collection of various specifications and documentation related to the Interledger Protocol (ILP). These documents or requests-for-comment (RFCs) are published by various authors and publication here does not imply official status unless otherwise specified in the document.
 
+The process for submitting an RFC is documented in the [RFC Process](CONTRIBUTING.md).
+
 For the main reference implementation of the ILP stack, see [Interledger.js](https://github.com/interledgerjs).
 
 ## Index

circle.yml

@@ -7,8 +7,6 @@ machine:
     - git config --global push.default simple
 test:
   override:
-    - echo "no tests"
-  post:
     # Generate graphs for specs
     - node scripts/generate_graphs.js
     # Generate specs for website

package.json

@@ -7,6 +7,7 @@
   "devDependencies": {
     "cheerio": "^0.20.0",
     "ejs": "^2.4.1",
+    "front-matter": "^2.1.2",
     "glob": "^7.0.3",
     "marked": "^0.3.5",
     "viz.js": "^1.7.1"

scripts/generate_web.js

@@ -7,6 +7,7 @@ const path = require('path')
 const exec = require('child_process').execSync
 const marked = require('marked')
 const cheerio = require('cheerio')
+const fm = require('front-matter')
 
 // We need a custom renderer to make sure we generate the same header IDs as
 // Github.
@@ -18,15 +19,15 @@ renderer.heading = function (text, level, raw) {
     .replace(/ /g, '-')
 
   return '<h'
-  + level
-  + ' id="'
-  + this.options.headerPrefix
-  + candidateId
-  + '">'
-  + text
-  + '</h'
-  + level
-  + '>\n';
+    + level
+    + ' id="'
+    + this.options.headerPrefix
+    + candidateId
+    + '">'
+    + text
+    + '</h'
+    + level
+    + '>\n';
 }
 
 // Override relative links from .md files to the base folder
@@ -46,12 +47,44 @@ exec('cp -r asn1 web/asn1', { cwd })
 
 const template = ejs.compile(fs.readFileSync('tmpl/rfc.ejs.html', 'utf8'))
 const files = glob.sync('????-*/????-*.md')
+let buildPass = true
 
 files.forEach((file) => {
-  const markdownContent = fs.readFileSync(file, 'utf8')
-  const renderedMarkdown = marked(markdownContent, { renderer })
+
+  const fileContent = fs.readFileSync(file, 'utf8')
+  const fmContent = fm(fileContent)
+
+  if(fmContent.attributes.deprecated) {
+    console.log("Skipped deprecated RFC in " + file)
+    return
+  }
+
+  if(!fmContent.attributes.title) {
+    buildPass = false;
+    console.error("No title specified for " + file)
+    return
+  }
+  const title = fmContent.attributes.title
+
+  if(!fmContent.attributes.draft) {
+    buildPass = false;
+    console.error("Draft number required for " + file)
+    return
+  }
+  const draftNumber = fmContent.attributes.draft
+
+  if((draftNumber^0) !== draftNumber && draftNumber !== 'FINAL') {
+    buildPass = false;
+    console.error("Invalid draft number found for " + file)
+    return
+  }
+
+  const renderedMarkdown = marked(fmContent.body, { renderer })
   const $ = cheerio.load(renderedMarkdown)
-  const title = $('h1').text()
+
+  const permalink = './draft-' + draftNumber + '.html'
+  const draftFile = 'web/' + path.dirname(file) + '/draft-' + draftNumber + '.html'
+  const indexFile = 'web/' + path.dirname(file) + '/index.html'
 
   // Ensure heading IDs are unique
   const idMap = new Map()
@@ -91,10 +124,25 @@ files.forEach((file) => {
   $('img').addClass('img-responsive')
 
   const content = $.html()
+  const renderedHtml = template({ title, content, toc, permalink })
+
+  //Versioning
+  if (fs.existsSync(draftFile)) {
+    const existingHtml = fs.readFileSync(draftFile, 'utf8')
+    if (existingHtml != renderedHtml) {
+      console.error('Draft number must be incremented if content is changed for ' + file)
+      buildPass = false
+      return
+    }
+    console.log('No changes in ' + file)
+    return
+  }
 
-  const renderedHtml = template({ title, content, toc })
+  console.log('Writing ' + draftFile)
+  fs.writeFileSync(draftFile, renderedHtml)
+  console.log('Writing ' + indexFile)
+  fs.writeFileSync(indexFile, renderedHtml)
 
-  fs.writeFileSync('web/' + path.dirname(file) + '/index.html', renderedHtml)
 })
 
 cwd = path.resolve(__dirname, '../web')
@@ -104,3 +152,5 @@ if (!status.length) {
 } else {
   console.log(status)
 }
+
+process.exit(buildPass ? 0 : 1)

tmpl/rfc.ejs.html

@@ -65,6 +65,11 @@
           <nav class="col-sm-4" id="myScrollspy">
             <ul class="nav-fixed nav nav-sidebar">
               <div class="overview-back"><a href="/overview.html"><i class="fa fa-angle-double-left" aria-hidden="true"></i> Back to Overview</a></div>
+              <% if(permalink) { %>
+                <li class="nav-label">
+                  <a href="<%= permalink %>">Permalink to this draft</a>
+                </li>
+              <% } %>
               <% toc.forEach((entry) => { %>
                 <li<%- (entry.type === 'h2') ? ' class="nav-label"' : '' %>>
                   <a href="#<%= entry.anchor %>"><%= entry.title %></a>