Merge pull request #862 from ianlewis/version-warning

feat: Add notice if viewing outdated versions of the spec
slsa-framework · May 17, 2023 · ca2d4e9 · ca2d4e9
2 parents d799c7b + 7ffa5f3
commit ca2d4e9
Show file tree

Hide file tree

Showing 6 changed files with 47 additions and 80 deletions.
diff --git a/docs/_data/versions.yml b/docs/_data/versions.yml
@@ -1,18 +1,22 @@
 # This file controls the version selector
 # Schema:
 #     <spec>:
+#       name: <string>                # display name
+#       current: <version>            # the current version id.
 #       versions:
-#         <version>:
-#           name: <string> # display name
-#           status: <string> # one of: Draft, Candidate, Approved, Retired
-#           draft: <bool, optional> # if true, display a "draft" warning banner
-#           hidden: <bool, optional> # if true, do not show in dropdown
+#         <version>:                  # version id; used in url path.
+#           name: <string>            # display name
+#           status: <string>          # one of: Draft, Candidate, Approved, Retired
+#           draft: <bool, optional>   # if true, display a "draft" warning banner
+#           hidden: <bool, optional>  # if true, do not show in dropdown
 #
 # Where:
 #   <spec> = specification name, i.e. first component of the URL
 #   <version> = version name, i.e. second component of the URL, e.g. v1.0
 
 spec:
+  name: Core specification
+  current: v1.0
   versions:
     v0.1:
       name: Version 0.1
@@ -30,6 +34,8 @@ spec:
       status: Approved
 
 provenance:
+  name: Provenance attestation
+  current: v1
   versions:
     v0.1:
       name: Version 0.1
@@ -50,6 +56,8 @@ provenance:
       status: Approved
 
 verification_summary:
+  name: Verification summary (VSA)
+  current: v1
   versions:
     v0.1:
       name: Version 0.1

diff --git a/docs/_includes/header.html b/docs/_includes/header.html
@@ -48,16 +48,39 @@
 </header>
 
 {%- assign url_parts = page.url | split: '/' %}
-{%- assign spec_name = url_parts[1] %}
+{%- assign spec_id = url_parts[1] %}
 {%- assign spec_version = url_parts[2] %}
-{%- if site.data.versions[spec_name].versions[spec_version].draft %}
-<input id="important-messages-checkbox" type="checkbox" hidden>
-<section class="important-messages">
-  <div>
-    <label for="important-messages-checkbox" title="dismiss">✕</label>
-    <p>This is a working draft of {{ spec_version }}.</p>
-    <p style="font-size: smaller">For the latest release candidate or approved
-      version, please use the version selector.</p>
-  </div>
-</section>
+{%- assign spec = site.data.versions[spec_id] %}
+{%- assign version = spec.versions[spec_version] %}
+{%- if spec and version %}
+  {%- if spec_version != spec.current or version.draft %}
+    <input id="important-messages-checkbox" type="checkbox" hidden>
+    <section class="important-messages">
+      <div>
+        <label for="important-messages-checkbox" title="dismiss">✕</label>
+        {%- if version.draft %}
+        <p>This is a working draft of {{ spec_version }}.</p>
+        <p style="font-size: smaller">For the latest release candidate or approved
+          version, please use the version selector.</p>
+        {%- endif %}
+
+        {%- if spec_version != spec.current %}
+          {%- assign current_version = spec.versions[spec.current] %}
+          {%- if current_version %}
+            {%- comment %}
+            Check if there is a page for the newest version. If there is link there, otherwise link to the spec version top page.
+            {% endcomment %}
+            {%- assign other_version = page.url | replace: spec_version, spec.current | relative_url -%}
+            {%- assign other_page = site.pages | where_exp: "page", "page.url == other_version" | first -%}
+            {%- if other_page %}
+              {%- assign new_url = other_page.url %}
+            {%- else %}
+              {%- assign new_url = "/" + spec_id + "/" + spec.current %}
+            {%- endif %}
+            <p>{{ spec.name }} {{ current_version.name | downcase }} is available now! See the newest documentation <a href="{{ new_url }}">here</a>.</p>
+          {%- endif %}
+        {%- endif %}
+      </div>
+    </section>
+  {%- endif %}
 {%- endif %}
diff --git a/docs/provenance/v0.1.md b/docs/provenance/v0.1.md
@@ -11,23 +11,6 @@ something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
-<details>
-<summary>Note about 0.x versions</summary>
-
-We expect regular iteration on 0.x versions until 1.0. During 0.x, we lean
-towards smaller, faster releases in order to get earlier feedback on the design.
-After 1.0, we will limit the frequency of breaking changes.
-
-To make this manageable, we recommend that:
-
--   Provenance generators choose the latest 0.x version at the time of
-    implementation and then stick with that until 1.0 unless there is reason to
-    upgrade before then.
--   Provenance consumers accept all known versions and convert internally
-    between them.
-
-</details>
-
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced.

diff --git a/docs/provenance/v0.2.md b/docs/provenance/v0.2.md
@@ -11,23 +11,6 @@ something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
-<details class="mt-12">
-<summary>Note about 0.x versions</summary>
-
-We expect regular iteration on 0.x versions until 1.0. During 0.x, we lean
-towards smaller, faster releases in order to get earlier feedback on the design.
-After 1.0, we will limit the frequency of breaking changes.
-
-To make this manageable, we recommend that:
-
--   Provenance generators choose the latest 0.x version at the time of
-    implementation and then stick with that until 1.0 unless there is reason to
-    upgrade before then.
--   Provenance consumers accept all known versions and convert internally
-    between them.
-
-</details>
-
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced.

diff --git a/docs/verification_summary/v0.1.md b/docs/verification_summary/v0.1.md
@@ -7,21 +7,6 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
-<details class="mt-12">
-<summary>Note about 0.x versions</summary>
-
-We expect regular iteration on 0.x versions until 1.0. During 0.x, we lean
-towards smaller, faster releases in order to get earlier feedback on the design.
-After 1.0, we will limit the frequency of breaking changes.
-
-To make this manageable, we recommend that:
-
--   Generators choose the latest 0.x version at the time of implementation and
-    then stick with that until 1.0 unless there is reason to upgrade before then.
--   Consumers accept all known versions and convert internally between them.
-
-</details>
-
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at

diff --git a/docs/verification_summary/v0.2.md b/docs/verification_summary/v0.2.md
@@ -7,21 +7,6 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
-<details class="mt-12">
-<summary>Note about 0.x versions</summary>
-
-We expect regular iteration on 0.x versions until 1.0. During 0.x, we lean
-towards smaller, faster releases in order to get earlier feedback on the design.
-After 1.0, we will limit the frequency of breaking changes.
-
-To make this manageable, we recommend that:
-
--   Generators choose the latest 0.x version at the time of implementation and
-    then stick with that until 1.0 unless there is reason to upgrade before then.
--   Consumers accept all known versions and convert internally between them.
-
-</details>
-
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at