feat: better status messages for the upcoming version pages

ethanresnick · ethanresnick · commit b5dc873ea108 · 2018-12-02T14:37:16.000-05:00
Show the release date, when there is one, and add the concept of a
“release candidate” stage (where the spec is subject to small changes
based on implementor experience) vs a “working draft” stage (where we
make no guarantees about what might still change, aside from our
existing backwards compatibility promises).
diff --git a/_format/upcoming/index.md b/_format/upcoming/index.md
@@ -1,5 +1,7 @@
 ---
 is_upcoming_version: true
+status: rc
+release_date: 2019-01-31
 ---
 {% for spec_draft in site.format %}
   {% if spec_draft.version > site.latest_version and spec_draft.path contains 'index' %}
diff --git a/_includes/status.md b/_includes/status.md
@@ -6,32 +6,43 @@
 {% assign version = include.version %}
 {% assign is_latest_version_page = include.is_latest_version %}
 {% assign is_upcoming_version_page = include.is_upcoming_version %}
+{% assign status = include.status %}
 
 ## <a href="#status" id="status" class="headerlink"></a> Status
 
 {% comment %}
-  The first paragraph in each case, below, aims to explain what content
-  the page holds and how that may (or may not) change over time.
+  The first paragraph in each case below aims to explain what content
+  the page holds and whether that content is finalized.
 
   Note: all the text below must be outdented and markdownified where it's
   included for it to be rendered correctly as markdown.
 {% endcomment %}
 
 {% if is_latest_version_page %}
-  This page represents the latest published version of JSON:API, which is
+  This page presents the latest published version of JSON:API, which is
   currently version {{ site.latest_version }}. New versions of JSON:API **will
   always be backwards compatible** using a _never remove, only add_ strategy.
   Additions can be proposed in our [discussion forum](http://discuss.jsonapi.org/).
 
 {% elsif is_upcoming_version_page %}
-  This page represents the **working draft** for the next version of JSON:API,
-  which is currently expected to be {{ site.latest_version|plus:0.1 }}.
+  This page presents the **{% if status == "rc" %}release candidate{% else %}
+  working draft{% endif %}** for the next version of JSON:API, which is 
+  expected to be {{ site.latest_version|plus:0.1 }}. {% if status != "rc" %}
+  As a draft, the content on this page is subject to change.{% else %}As a 
+  release candidate, the content on this page is unlikely to change. However, 
+  some changes may still occur if implementation experience proves that they are 
+  necessary before this version is finalized.{% endif %}
+
+  {% if include.release_date %}
+  This version is expected to be finalized and released on 
+  **{{ include.release_date | date: "%B %e, %Y" }}** (provided there are two compliant implementations by that date; if not the release will wait until such implementations exist to prove its viability).
+  {% endif %}
+
 
 {% elsif version and version > site.latest_version %}
   This page will always present the most recent text for JSON:API
-  v{{ site.latest_version|plus:0.1 }}. Currently, version
-  {{ site.latest_version|plus:0.1 }} is **still a draft**, so this text is
-  provisional.
+  v{{ site.latest_version|plus:0.1 }}. Version {{ site.latest_version|plus:0.1 }}
+  has not been finalized, so the text here may change.
 
 {% elsif version and version == site.latest_version %}
   This page presents an archived copy of JSON:API version {{ version }}. None
diff --git a/_layouts/page.html b/_layouts/page.html
@@ -87,7 +87,7 @@ <h1>
         <section>
           {% if page.is_spec_page %}
             {% capture status %}
-              {% include status.md version=page.version is_latest_version=page.is_latest_version is_upcoming_version=page.is_upcoming_version %}
+              {% include status.md release_date=page.release_date status=page.status version=page.version is_latest_version=page.is_latest_version is_upcoming_version=page.is_upcoming_version %}
             {% endcapture %}
             {{ status|strip|markdownify }}
           {% endif %}
