Create /final/ permalinks for final CAIPs

.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_PATH: "localgemstore"

.gitignore

@@ -2,4 +2,4 @@ _site
 .sass-cache
 .jekyll-cache
 .jekyll-metadata
-vendor
+localgemstore

CAIPs/caip-1.md

@@ -5,7 +5,7 @@ status: Review
 type: Meta
 author: ligi <[email protected]>
 created: 2019-08-31
-updated: 2019-08-31
+updated: 2024-04-15
 ---
 
 ## What is an CAIP?
@@ -33,7 +33,7 @@ Each CAIP must begin with an [RFC 822](https://www.ietf.org/rfc/rfc822.txt) styl
 
 ` * discussions-to:` \<a URL pointing to the official discussion thread\>
 
-` status:` <Draft | Rejected | Review | Last Call | Withdrawn | Final | Superseded>
+` status:` <Draft | Rejected | Review | Last Call | Withdrawn | Superseded | Final>
 
 `* review-period-end:` <date review period ends>
 
@@ -95,9 +95,13 @@ The `updated` header records the date(s) when the CAIP was updated with "substan
 
 CAIPs may have a `requires` header, indicating the CAIP(s) on which this CAIP depends. Note that if the CAIP requires multiple others, the value should be an array of integers (no `"` needed) and/or URLs (wrapped in `"`s) within square brackets (`[]`).
 
-#### `superseded-by` and `replaces` headers
+#### `status` header
 
-CAIPs may also have a `superseded-by` header indicating that a CAIP has been rendered obsolete by a later document; the value is the number of the CAIP that replaces the current document. The newer CAIP must have a `replaces` header containing the number of the CAIP that it rendered obsolete.
+The status header refers to the editorial lifecycle, as attested by the author(s) of a given proposal. 
+
+`Review` and `Last Call` (an optional subset of `Review` expressing urgency to reviewers) should used in combination with the optional parameter `review-period-end` to express the review deadline to which the author is commits themself. 
+
+`Superseded` is a variant of `Withdrawn` which redirects readers to another proposal; here as well, the optional parameters `superseded-by` (on the superseded proposal) and `replaces` (on the superseding proposal) help link these proposals. `Final` proposals cannot be changed to `Withdrawn` or `Superseded`.
 
 ## Auxiliary Files
 
@@ -129,9 +133,9 @@ Once the CAIP is ready for the repository, the CAIP editor will:
 
 - Merge the corresponding pull request
 
-- Send a message back to the CAIP author with the next step.
+- Leave a comment making explicit to the CAIP author(s) what the next steps are.
 
-The editors don't pass judgment on CAIPs. We merely do the administrative & editorial part.
+The editors don't pass judgment on CAIPs. We merely do the administrative & editorial part. Substantive and normative judgments should be made by author(s) whenever possible.
 
 ## History
 

CONTRIBUTING.md

@@ -5,15 +5,24 @@
 3.  Add your CAIP to your fork of the repository. There is a [template CAIP here](caip-template.md).
 4.  Submit a Pull Request to Chain Agnostics's [CAIPs repository](https://github.com/ChainAgnostic/CAIPs).
 
-Your first PR should be a first draft of the complete and implementable CAIP. 
-An editor will manually review the first PR for a new CAIP and assign it a number before merging it.
+Your first Pull Request (hereafter "PR") should be a first draft of the complete and implementable CAIP; the CAIP number will be taken from the PR that creates it, unless a different number is requested or assigned by an editor.
+An editor will manually review the first PR and, if necessary, [re-]assign a number before merging it.
 Make sure you include a `discussions-to` header with the URL of an issue or discussion on this repository, or any other forum where you would welcome discussion.
 
 If your CAIP requires images, the image files should be included in a subdirectory of the `assets` folder for that CAIP as follows: `assets/caip-N` (where **N** is to be replaced with the CAIP number). 
 When linking to an image in the CAIP, use relative links such as `../assets/caip-1/image.png`.
 
 It is recommended that you render your PR locally to check the Jekyll syntax; to do so, run `bundle exec jekyll serve`.
 
+## Status Lifecycle (see CAIP-1)
+
+We recommend all specifications be published in "Draft" status initially.
+We recommend not changing the status to "Review" until there is at least 1 reviewable implementation and other potential implementers are evaluating or considering implementing.
+Editors reserve the right to mark a "Draft" as "Stale" after significant periods of inactivity, or authors can mark them as such themselves.
+We recommend moving from "Review" to "Final" only when interoperability and further adoption is hindered by the risk of breakage.
+
+Note: When opening a PR to "Final" status that a second, identical copy of the file and any assets or attachments should be placed in the "/final" folder to render a second copy at the `/final` path (this allows "Final"-status CAIPs to be marked as such at archival URLs).
+
 ## Style Guide
 
 Github-flavored Markdown is encouraged for all CAIP documents, with the following conventions observed:

Gemfile.lock

@@ -1,18 +1,18 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
+    addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     colorator (1.1.0)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.2.3)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.15.5)
+    ffi (1.16.3)
     forwardable-extended (2.6.0)
     http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    i18n (1.14.4)
       concurrent-ruby (~> 1.0)
     jekyll (4.2.2)
       addressable (~> 2.4)
@@ -29,7 +29,7 @@ GEM
       rouge (~> 3.0)
       safe_yaml (~> 1.0)
       terminal-table (~> 2.0)
-    jekyll-feed (0.16.0)
+    jekyll-feed (0.17.0)
       jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (2.2.0)
       sassc (> 2.0.1, < 3.0)
@@ -41,8 +41,8 @@ GEM
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    liquid (4.0.3)
-    listen (3.7.1)
+    liquid (4.0.4)
+    listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
@@ -52,11 +52,11 @@ GEM
       jekyll-seo-tag (~> 2.1)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.0)
+    public_suffix (5.0.4)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
+    rexml (3.2.6)
     rouge (3.30.0)
     safe_yaml (1.0.5)
     sassc (2.4.0)
@@ -67,6 +67,7 @@ GEM
     webrick (1.8.1)
 
 PLATFORMS
+  ruby
   x86_64-linux
 
 DEPENDENCIES
@@ -80,4 +81,4 @@ DEPENDENCIES
   webrick (~> 1.8)
 
 BUNDLED WITH
-   2.3.24
+   2.5.6

_config.yml

@@ -21,7 +21,7 @@
 title: Chain Agnostic Improvement Proposals
 description: >- # this means to ignore newlines until "baseurl:"
   Chain Agnostic Improvement Proposals (CAIPs) describe standards for blockchain projects that are not specific to a single chain.
-url: "" # the base hostname & protocol for your site, e.g. http://example.com
+baseurl: "" # the base hostname & protocol for your site, e.g. http://example.com
 github_username: ChainAgnostic
 repository: ChainAgnostic/CAIPs
 
@@ -35,13 +35,18 @@ markdown: kramdown
 plugins:
   - jekyll-feed
 
-permalink: /:slug
+permalink: /:path
 
 defaults:
   - scope:
       path: "CAIPs"
     values:
       layout: "caip"
+  - scope:
+      path: "final"
+    values:
+      layout: "caip-final"
 
 exclude:
   - caip-template.md
+

_includes/caiptable.html

@@ -22,14 +22,16 @@ <h2 id="{{status|slugify}}">{{status}}</h2>
           {% endif %}
         </thead>
         {% for page in caips %}
-          <tr>
-            <td class="num"><a href="{{page.url|relative_url}}">{{page.caip|xml_escape}}</a></td>
-            {% if status == "Last Call" and page.last-call-deadline != undefined %}
-              <td class="date">{{ page.last-call-deadline | xml_escape }}</td>
-            {% endif %}
-            <td class="title">{{page.title|xml_escape}}</td>
-            <td class="author">{% include authorlist.html authors=page.author %}</td>
-          </tr>
+          {% unless page.path contains "final" %}
+            <tr>
+              <td class="num"><a href="{{page.url|relative_url}}">{{page.caip|xml_escape}}</a></td>
+              {% if status == "Last Call" and page.last-call-deadline != undefined %}
+                <td class="date">{{ page.last-call-deadline | xml_escape }}</td>
+              {% endif %}
+              <td class="title">{{page.title|xml_escape}}</td>
+              <td class="author">{% include authorlist.html authors=page.author %}</td>
+            </tr>
+          {% endunless %}
         {% endfor %}
       </table>
     {% endif %}

_layouts/caip-final.html

@@ -0,0 +1,116 @@
+---
+layout: default
+---
+
+<div class="home">
+  <h1 class="page-heading">
+    CAIP-{{ page.caip | xml_escape }}: {{ page.title | xml_escape }}
+    <a href="https://github.com/{{site.repository}}/blob/main/{{page.path}}"><svg aria-hidden="true" height="24" viewBox="0 0 16 16" version="1.1" width="24" data-view-component="true" class="octicon octicon-mark-github">
+      <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path>
+      </svg></a>
+  </h1>
+  <h3>{{ page.description | xml_escape }}</h3>
+  <table>
+    <tr>
+      <th>Author</th>
+      <td>{% include authorlist.html authors=page.author %}</td>
+    </tr>
+    {% if page["discussions-to"] != undefined %}
+    <tr>
+      <th>Discussions-To</th>
+      <td>{% include discussion_links.html links=page.discussions-to %}</td>
+    </tr>
+    {% endif %}
+    <tr>
+      <th>Status</th>
+      <td>
+        {{ page.status | xml_escape }}
+        {% if page.last-call-deadline != undefined %}
+      </td>
+    </tr>
+    <tr>
+      <th>Last Call Deadline</th>
+      <td>{{ page.last-call-deadline | xml_escape }}</td>
+    </tr>
+    {% endif %}
+    </td>
+    </tr>
+    <tr>
+      <th>Type</th>
+      <td>{{ page.type | xml_escape }}</td>
+    </tr>
+    {% if page.category != undefined %}
+    <tr>
+      <th>Category</th>
+      <td>{{ page.category | xml_escape }}</td>
+    </tr>
+    {% endif %}
+    <tr>
+      <th>Created</th>
+      <td>{{ page.created | xml_escape }}</td>
+    </tr>
+    {% if page.updated != undefined %}
+    <tr>
+      <th>Updated</th>
+      <td>{{ page.updated | xml_escape }}</td>
+    </tr>
+    {% endif %}
+    {% if page.requires != undefined %}
+    <tr>
+      <th>Requires</th>
+      <td>{% include caipnums.html caips=page.requires %}</td>
+    </tr>
+    {% endif %}
+    {% if page.superseded-by != undefined %}
+    <tr>
+      <th>Superseded By</th>
+      <td>{% include superseded_by.html caips=page.superseded-by %}</td>
+    </tr>
+    {% endif %}
+    {% if page["withdrawal-reason"] != undefined %}
+    <tr>
+      <th>Withdrawal reason</th>
+      <td>{{ page["withdrawal-reason"] | xml_escape }}</td>
+    </tr>
+    {% endif %}
+  </table>
+
+  <div class="toc">
+    <h2>Table of Contents</h2>
+    {% include toc.html html=content sanitize=true h_max=3 %}
+  </div>
+
+  {% include anchor_headings.html html=content anchorClass="anchor-link" beforeHeading=true %}
+
+  <h2>Citation</h2>
+  <p>Please cite this document as:</p>
+  {% comment %}
+  IEEE specification for reference formatting:
+  https://ieee-dataport.org/sites/default/files/analysis/27/IEEE%20Citation%20Guidelines.pdf
+  {% endcomment %}
+  <p>{% include authorlist.html authors=page.author %}, "CAIP-{{ page.caip | xml_escape }}: {{ page.title | xml_escape
+    }}{% if page.status == "Draft" or page.status == "Last Call" or page.status == "Abandoned" %} [DRAFT]{% endif %}," <em>Chain Agnostic Improvement Proposals</em>, no. {{
+    page.caip | xml_escape }}, {{ page.created | date: "%B %Y" }}. [Online serial]. Available:
+    https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-{{ page.caip | xml_escape }}.md</p>
+</div>
+{% comment %}
+Article schema specification:
+https://schema.org/TechArticle
+{% endcomment %}
+<script type="application/ld+json">
+  {
+    "@context": "http://schema.org",
+    "@type": "TechArticle",
+    "headline": "CAIP-{{ page.caip | xml_escape }}: {{ page.title | xml_escape }}{% if page.status == "Draft" or page.status == "Last Call" or page.status == "Abandoned" %} [DRAFT]{% endif %}",
+    "author": "{{ page.author }}",
+    "name": "CAIP-{{ page.caip | xml_escape }}: {{ page.title | xml_escape }}{% if page.status == "Draft" or page.status == "Last Call" or page.status == "Abandoned" %} [DRAFT]{% endif %}",
+    "dateCreated": "{{ page.created | date: "%Y-%m-%d" }}",
+    "datePublished": "{{ page.created | date: "%Y-%m-%d" }}",
+{% if page["discussions-to"] != undefined %}
+    "discussionUrl": "{{ page["discussions-to"] | uri_escape }}",
+{% endif %}    
+    "inLanguage": "en-US",
+    "license": "#copyright",
+    "copyrightYear": "{{ page.created | date: "%Y" }}"
+  }
+</script>

_layouts/caip.html

@@ -23,8 +23,15 @@ <h3>{{ page.description | xml_escape }}</h3>
     {% endif %}
     <tr>
       <th>Status</th>
-      <td>{{ page.status | xml_escape }}
+      <td>
+        {% if page.status contains "Final" %}
+        <a href=/final/{{ page.slug | xml_escape }}>Final</a>
+        {% else %}
+          {{ page.status | xml_escape }}
+        {% endif %}
         {% if page.last-call-deadline != undefined %}
+      </td>
+    </tr>
     <tr>
       <th>Last Call Deadline</th>
       <td>{{ page.last-call-deadline | xml_escape }}</td>