editorial: move provenance and VSA under spec dir (slsa-framework#939)

Redirect /provenance/v1 and /verification_summary/v1 to
/spec/v1.0/provenance and /spec/v1.0/verification_summary, respectively,
and similarly for older versions. (`predicateType` URIs do NOT change.)

Reasons for this change:

- Make it obvious to the reader that all three are versioned together
  and that they form one cohesive specification.
- Make it easier to implement versioning via branches/tags. Previously
  we would have had to have either three separate sets of branches/tags
  or three sets of directories within each branch/tag, and then merge
  files within one directory. Now we can have each version directory
  correspond to a branch/tag, which is simpler to understand and
  maintain.
- To show the minor version in the URL bar, without affecting the
  major-version-only `predicateType`.

Related changes:

- Redirect old URLs to the new location to allow them to continue
  working.
- Update any existing links that would have been broken by the change,
  namely links to `.md` files and links using relative paths.
  - Do not update links to redirected URLs, in order to minimize the
    size of this PR. Optionally, a future PR could clean this up.
- Move images and schema files too, since (a) links have to be updated
  anyway and (b) it aligns with slsa-framework#936.
- Fix the version selector to properly handle v0.2, which only exists
  for provenance and verification_summary.
  - Also remove the name "Core specification" from the banner since is
    now the only specification.
- Add provenance and verification_summary the "onepage" view. This was
  not possible before.

Ideally this would have been broken up into smaller changes, but I could
not figure out a way to do so that would have left the site continuing
to work.

Signed-off-by: Mark Lodato <lodato@google.com>

docs/_data/nav/v0.1.yml

@@ -37,10 +37,10 @@
         url: /attestation-model
 
       - title: Provenance
-        url: /provenance/v0.1
+        url: /spec/v0.1/provenance
 
       - title: VSA
-        url: /verification_summary/v0.1
+        url: /spec/v0.1/verification_summary
 
     - title: Stages
       url: /spec-stages

docs/_data/nav/v0.2.yml

@@ -37,10 +37,10 @@
         url: /attestation-model
 
       - title: Provenance
-        url: /provenance/v0.2
+        url: /spec/v0.2/provenance
 
       - title: VSA
-        url: /verification_summary/v0.2
+        url: /spec/v0.2/verification_summary
 
     - title: Stages
       url: /spec-stages

docs/_data/nav/v1.0-rc1.yml

@@ -49,10 +49,10 @@
         url: /attestation-model
 
       - title: Provenance
-        url: /provenance/v1-rc1
+        url: /spec/v1.0-rc1/provenance
 
       - title: VSA
-        url: /verification_summary/v1-rc1
+        url: /spec/v1.0-rc1/verification_summary
 
     - title: Stages
       url: /spec-stages

docs/_data/nav/v1.0-rc2.yml

@@ -86,11 +86,11 @@
     description: General attestation mode
 
   - title: Provenance
-    url: /provenance/v1-rc2
+    url: /spec/v1.0-rc2/provenance
     description: Suggested provenance format and explanation
 
   - title: VSA
-    url: /verification_summary/v1-rc2
+    url: /spec/v1.0-rc2/verification_summary
     description: Suggested VSA format and explanation
 
 - title: How to SLSA

docs/_data/nav/v1.0.yml

@@ -86,11 +86,11 @@
     description: General attestation mode
 
   - title: Provenance
-    url: /provenance/v1
+    url: /spec/v1.0/provenance
     description: Suggested provenance format and explanation
 
   - title: VSA
-    url: /verification_summary/v1
+    url: /spec/v1.0/verification_summary
     description: Suggested VSA format and explanation
 
 - title: How to SLSA

docs/_data/versions.yml

@@ -1,74 +1,38 @@
 # This file controls the version selector
 # Schema:
 #     <spec>:
-#       name: <string>                # display name
 #       current: <version>            # the current version id.
 #       versions:
 #         <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
+#           unhide_for: <array[string], optional>  # do not hide for these pages
 #
 # 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
       status: Approved
-    v1.0-rc1:
-      name: Version 1.0 RC1
-      status: Retired
-      hidden: true
-    v1.0-rc2:
-      name: Version 1.0 RC2
-      status: Retired
-      hidden: true
-    v1.0:
-      name: Version 1.0
-      status: Approved
-
-provenance:
-  name: Provenance attestation
-  current: v1
-  versions:
-    v0.1:
-      name: Version 0.1
-      status: Retired
     v0.2:
       name: Version 0.2
       status: Approved
-    v1-rc1:
-      name: Version 1.0 RC1
-      status: Retired
       hidden: true
-    v1-rc2:
-      name: Version 1.0 RC2
+      unhide_for: [provenance, verification_summary]
+    v1.0-rc1:
+      name: Version 1.0 RC1
       status: Retired
       hidden: true
-    v1:
-      name: Version 1.0
-      status: Approved
-
-verification_summary:
-  name: Verification summary (VSA)
-  current: v1
-  versions:
-    v0.1:
-      name: Version 0.1
-      status: Retired
-    v0.2:
-      name: Version 0.2
-      status: Approved
-    v1-rc2:
+    v1.0-rc2:
       name: Version 1.0 RC2
       status: Retired
       hidden: true
-    v1:
+    v1.0:
       name: Version 1.0
       status: Approved

docs/_includes/header.html

@@ -77,7 +77,7 @@
             {%- 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>
+            <p>{{ current_version.name }} is available now! See the newest documentation <a href="{{ new_url }}">here</a>.</p>
           {%- endif %}
         {%- endif %}
       </div>

docs/_includes/versions-dropdown.html

@@ -1,6 +1,7 @@
 {%- assign url_parts = page.url | split: '/' %}
 {%- assign spec_name = url_parts[1] %}
 {%- assign spec_version = url_parts[2] %}
+{%- assign spec_page = url_parts[3] %}
 {%- if site.data.versions[spec_name].versions[spec_version] %}
 {%- assign versions = site.data.versions[spec_name].versions | sort %}
 <select id="redirectSelect.{{include.laptop}}" class="select-dropdown p-1 mx-1 my-4 text-black opacity-80
@@ -9,7 +10,11 @@
   {%- else %} border-gray-400
   {%- endif %}">
 {%- for item in versions reversed %}
-{%- unless item[1].hidden and spec_version != item[0] %}
+  {%- if item[1].hidden %}
+    {%- unless spec_version == item[0] or item[1].unhide_for contains spec_page %}
+      {%- continue %}
+    {%- endunless %}
+  {%- endif %}
   {%- assign page_url_parts = page.url | split: '/' %}
   {%- assign page_url = page_url_parts | join: '/' %}
   {%- assign other_version = page_url | replace: spec_version, item[0] | relative_url %}
@@ -25,8 +30,6 @@
     {%- assign state = "disabled" %}
   {%- endif %}
 <option {{ state }} value="{{ other_version }}" class="inline-block">{{item[1].name}}</option>
-
-{%- endunless %}
 {%- endfor %}
 </select>
 <script>

docs/_posts/2023-04-03-the-breadth-and-depth-of-slsa.md

@@ -6,7 +6,7 @@ is_guest_post: false
 
 Interested in getting involved? Now’s the chance to [provide your feedback on the foundational v1 release of the SLSA framework.](2023-02-24-slsa-v1-rc.md)
 
-“Software Supply chain security is more than just the build” is a common response when folks learn about SLSA. This is true. SLSA 1.0 is entirely focused on generating [build provenance](../provenance/v1.md) and assurance around that provenance due to the security capabilities of the build system and security properties of a particular running build. Software Supply Chain Security is the cybersecurity practice of extending left into System Delivery Lifecycle or Software Delivery Lifecycle and the SDLC is more than just the build.
+“Software Supply chain security is more than just the build” is a common response when folks learn about SLSA. This is true. SLSA 1.0 is entirely focused on generating [build provenance](/spec/v1.0/provenance) and assurance around that provenance due to the security capabilities of the build system and security properties of a particular running build. Software Supply Chain Security is the cybersecurity practice of extending left into System Delivery Lifecycle or Software Delivery Lifecycle and the SDLC is more than just the build.
 
 If the SDLC is more than the build, why is the SLSA community only focused on that one aspect? We’re not. We’re just starting with the build. The initial focus on the **build track** is a strategic decision made due to its significance in the overall process. The build serves as the bridge between various inputs, such as source code and dependencies, and the final product, which is the software package or artifact intended to run in production environments or be used as a dependency to downstream consumers.
 

docs/_redirects

@@ -38,18 +38,31 @@
 /github-actions-workflow/v1         https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1    301
 /github-actions-workflow/v1.0       https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1    301
 
+/images/provenance/v1/model.svg         /spec/v1.0/images/provenance-model.svg      302
 /images/v1.0/supply-chain-threats-build-verification.svg    /spec/v1.0/images/supply-chain-threats-build-verification.svg   302
 /images/v1.0/supply-chain-threats.svg   /spec/v1.0/images/supply-chain-threats.svg  302
 /spec/v1.0/build-model.svg              /spec/v1.0/images/build-model.svg           302
 /spec/v1.0/verification-model.svg       /spec/v1.0/images/verification-model.svg    302
 
-/provenance             /provenance/v1          302
-/provenance/v0.2-draft  /provenance/v0.2        301
-/provenance/v1.0        /provenance/v1          302
+/provenance             /spec/v1.0/provenance       302  # floating
+/provenance/v0.1        /spec/v0.1/provenance       301
+/provenance/v0.2        /spec/v0.2/provenance       301
+/provenance/v0.2-draft  /spec/v0.2/provenance       301
+/provenance/v1          /spec/v1.0/provenance       302  # floating
+/provenance/v1-rc1      /spec/v1.0-rc1/provenance   301
+/provenance/v1-rc2      /spec/v1.0-rc2/provenance   301
+/provenance/v1.0        /spec/v1.0/provenance       301
 
 /spec                   /spec/v1.0              302
 /spec/faq               /spec/v1.0/faq          302
 /spec/v1/*              /spec/v1.0/:splat       302
 
-/verification_summary       /verification_summary/v1    302
-/verification_summary/v1.0  /verification_summary/v1    302
+# Note: Versions prior to v1.0 stay in /verification_summary.
+/verification_summary           /spec/v1.0/verification_summary     302  # floating
+/verification_summary/v0.1      /spec/v0.1/verification_summary     301
+/verification_summary/v0.2      /spec/v0.2/verification_summary     301
+/verification_summary/v1        /spec/v1.0/verification_summary     302  # floating
+# Note: there is no v1-rc1, so just redirect to rc2.
+/verification_summary/v1-rc1    /spec/v1.0-rc2/verification_summary 301
+/verification_summary/v1-rc2    /spec/v1.0-rc2/verification_summary 301
+/verification_summary/v1.0      /spec/v1.0/verification_summary     301

docs/attestation-model.md

@@ -156,7 +156,7 @@ recognize that other choices MAY be necessary in various cases.
 [Provenance]: /provenance
 [remote attestation]: https://en.wikipedia.org/wiki/Trusted_Computing#Remote_attestation
 [RFC 2119]: https://tools.ietf.org/html/rfc2119
-[SLSA Provenance format]: /provenance/v1.md
+[SLSA Provenance format]: /provenance/v1
 [sigstore/cosign]: https://github.com/sigstore/cosign
 [SPDX]: https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md
-[Verification Summary Attestation]: /verification_summary/v1.md
+[Verification Summary Attestation]: /verification_summary/v1

docs/provenance/v0.1.md → docs/spec/v0.1/provenance.md

@@ -45,7 +45,7 @@ external control.
 
 See [Example](#example) for a concrete example.
 
-![Model Diagram](../images/provenance/v0.1/provenance.svg)
+![Model Diagram](images/provenance.svg)
 
 ## Schema
 
@@ -502,4 +502,4 @@ Execution of arbitrary commands:
 [TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI
 [in-toto attestation]: https://github.com/in-toto/attestation
 [parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules
-[provenance requirements]: ../spec/v0.1/requirements#provenance-requirements
+[provenance requirements]: requirements#provenance-requirements

docs/provenance/v0.2.md → docs/spec/v0.2/provenance.md

@@ -46,7 +46,7 @@ environmental parameters (`environment`) that are needed for
 
 See [Example](#example) for a concrete example.
 
-![Model Diagram](../images/provenance/v0.2/provenance.svg)
+![Model Diagram](images/provenance.svg)
 
 ## Schema
 
@@ -632,7 +632,7 @@ To migrate from [version 0.1][0.1] (`old`):
 -   0.1.1: Added `metadata.buildInvocationId`.
 -   0.1: Initial version, named "in-toto.io/Provenance"
 
-[0.1]: v0.1.md
+[0.1]: /provenance/v0.1
 [DigestSet]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#DigestSet
 [GitHub Actions]: #github-actions
 [Reproducible]: https://reproducible-builds.org
@@ -642,4 +642,4 @@ To migrate from [version 0.1][0.1] (`old`):
 [TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI
 [in-toto attestation]: https://github.com/in-toto/attestation
 [parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules
-[provenance requirements]: ../spec/v0.1/requirements#provenance-requirements
+[provenance requirements]: ../v0.1/requirements#provenance-requirements

docs/spec/v1.0-rc1/onepage.md

@@ -7,6 +7,6 @@ A single page containing all the following files as different sections
 {%- endcomment -%}
 
 {% assign dir = "/spec/v1.0-rc1/" %}
-{% assign filenames = "levels,principles,terminology,requirements,verifying-systems,threats,faq,future-directions" %}
+{% assign filenames = "levels,principles,terminology,requirements,verifying-systems,threats,faq,future-directions,provenance,verification_summary" %}
 
 {% include onepage.liquid dir=dir filenames=filenames %}

docs/provenance/v1-rc1.md → docs/spec/v1.0-rc1/provenance.md

@@ -42,7 +42,7 @@ requirements](/spec/v1.0-rc1/requirements#provenance-generation).
 Provenance is an attestation that the `builder` produced the `subject` software
 artifacts through execution of the `buildDefinition`.
 
-![Build Model](../images/provenance/v1-rc1/model.svg)
+![Build Model](images/provenance-model.svg)
 
 The model is as follows:
 
@@ -111,16 +111,16 @@ understand cue. For that reason, we are not using any special cue syntax or
 features. -->
 
 ```javascript
-{% include_relative schema/v1-rc1/provenance.cue %}
+{% include_relative schema/provenance.cue %}
 ```
 
 <details>
 <summary>Protocol buffer schema</summary>
 
-Link: [provenance.proto](schema/v1-rc1/provenance.proto)
+Link: [provenance.proto](schema/provenance.proto)
 
 ```proto
-{% include_relative schema/v1-rc1/provenance.proto %}
+{% include_relative schema/provenance.proto %}
 ```
 
 </details>
@@ -194,7 +194,7 @@ reproducing the build. There is no need to [verify][Verification] these
 parameters because the build system is already trusted, and in many cases it is
 not practical to do so.
 
-***NOTE:** This field is named `internalParameters` in [v1](v1.md) final.*
+***NOTE:** This field is named `internalParameters` in [v1](/provenance/v1) final.*
 
 <tr id="resolvedDependencies"><td><code>resolvedDependencies</code>
 <td>array (<a href="#artifactreference">ArtifactReference</a>)<td>
@@ -676,8 +676,8 @@ validate that the design is general enough to apply to other builders.
 
 ## Migrating from 0.2
 
-To migrate from [version 0.2](../v0.2) (`old`), use the following pseudocode.
-The meaning of each field is unchanged unless otherwise noted.
+To migrate from [version 0.2](/provenance/v0.2) (`old`), use the following
+pseudocode. The meaning of each field is unchanged unless otherwise noted.
 
 ```javascript
 {

docs/spec/v1.0-rc2/onepage.md

@@ -8,6 +8,6 @@ A single page containing all the following files as different sections
 {%- endcomment -%}
 
 {% assign dir = "/spec/v1.0-rc2/" %}
-{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-systems,verifying-artifacts,threats" %}
+{% assign filenames = "whats-new,about,threats-overview,use-cases,principles,faq,future-directions,terminology,levels,requirements,distributing-provenance,verifying-systems,verifying-artifacts,threats,provenance,verification_summary" %}
 
 {% include onepage.liquid dir=dir filenames=filenames %}