nonspec: new website build strategy

.devcontainer/post-create.sh

@@ -14,5 +14,10 @@ bundle install
 # Install the Netlify CLI globally using npm
 npm install -g netlify-cli
 
+# Netlify 23.15.1 on ARM fails to install a working version of deno,
+# so install the latest one directly.
+# Note: this should not be necessary once netlify is fixed
+npm install -g deno
+
 # Return to the previous directory
 cd ..

.github/workflows/publish-spec.yml

@@ -0,0 +1,50 @@
+# This workflow publishes the SLSA specification as a GitHub Release when a commit is pushed to a release branch.
+# It creates a zip archive of the spec, generates a build provenance attestation, and attaches both to the release.
+name: Publish Spec as Release
+
+on:
+  push:
+    branches:
+      - 'releases/v*.*.*'
+
+jobs:
+  publish-spec:
+    permissions:
+      attestations: write # Needed to generate and upload build provenance attestations
+      packages: write # Required for provenance and artifact publishing features
+      contents: write # Allows creating, deleting, and updating releases and release assets
+      id-token: write # Grants access to the OIDC token for secure provenance attestation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Create source artifact
+        run: |
+          cd docs
+          zip -r spec.zip spec
+
+      - name: Set up GitHub CLI
+        uses: cli/gh-action@v2
+
+      - name: Generate build provenance attestation
+        run: |
+          gh attestation generate build-provenance \
+            --repo "$GITHUB_REPOSITORY" \
+            --subject-path docs/spec.zip \
+            --output docs/spec.attestation.json
+
+      - name: Create or recreate GitHub Release and upload assets
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Determine the release version from the Git ref
+          VERSION=${GITHUB_REF##*/}
+          # If a release with this version already exists, delete it to avoid errors
+          if gh release view "$VERSION" > /dev/null 2>&1; then
+            gh release delete "$VERSION" --yes
+          fi
+          # Create a new release and upload the spec artifact and attestation
+          gh release create "$VERSION" docs/spec.zip docs/spec.attestation.json \
+            --title "Release $VERSION" \
+            --notes "This is the release of the spec. The source artifact and attestation are attached."

.gitignore

@@ -3,9 +3,10 @@
 .jekyll-cache
 .jekyll-metadata
 .sass-cache
-_site
 node_modules
-/docs/vendor/bundle
+/www/vendor/bundle
+/www/spec
+_site
 
 # Ignore the following files markdownlint that are already tracked by git (thus
 # uanffected by gitignore).

CONTRIBUTING.md

@@ -80,23 +80,21 @@ VS Code will build the container and configure the development environment autom
 
 ### Deploying the site locally
 
-SLSA.dev is hosted on [Netlify](https://www.netlify.com/), and you can run a local development server using the Netlify CLI.
+For detailed instructions on building and testing the site locally, see [www/README.md](www/README.md#building-and-testing-locally).
 
-1.  Install the Netlify CLI globally if you haven't already:
+Quick start (from the repository root):
 
-    ```shell
-    npm install -g netlify-cli # this will be pre-installed in the DevContainer
-    ```
+```shell
+cd www
+../tools/combine-versions.sh
+netlify dev
+```
 
-2.  `cd` into the `docs` directory
-3.  Run the following command to start the local development server:
+Then browse to http://localhost:8888 to view the site locally.
 
-    ```shell
-    netlify dev
-    ```
+### Deploying the site in production
 
-4.  Open the browser and navigate to http://localhost:8888
-5.  Verify that the site is running locally
+For detailed instructions on deploying the site in production, see [www/README.md](www/README.md#production).
 
 ### Markdown style
 
@@ -185,7 +183,7 @@ approvers for their own PRs. For example, if the author of a PR with the
 two additional approvers before merging. However, a PR with the `impl` type
 always requires one reviewer, even if the author has write access.
 
-Note 2: If the PR only touches files in the [Draft](docs/spec-stages.md)
+Note 2: If the PR only touches files in the [Draft](www/spec-stages.md)
 specification stage, then the "waiting period" and "# reviewers" are relaxed and
 up to Maintainer discretion (including the PR author if they're a maintainer). Note
 that a relaxed number of reviewers and waiting period may result in more back
@@ -296,34 +294,32 @@ in your git config.
 
 ## SLSA versions management
 
-The main working draft is located in the `spec/draft` folder while the various versions are in specific folders:
+The main working draft is located in the `spec` folder with the various versions in branches a la "releases/v0.1", "releases/v1.0", etc.
+
+`spec` is where all new work should take place. To publish a new version of the SLSA specification, create a new branch (e.g., `releases/v1.1`) and make the necessary changes to the spec folder on that branch: it is possible for instance that not all that is in the draft should be included in which case you will need to remove that content, and several config and navigation files need to be updated such as:
 
 ```none
-spec/draft
-spec/v0.1
-spec/v0.2
-spec/v1.0
-spec/v1.0-rc1
-spec/v1.0-rc2
-spec/v1.1
+www/_data/nav/config.yml
+www/_data/nav/v1.1.yml (corresponding to the version you are creating)
+www/_data/versions.yml
+www/_redirects
 ```
 
-`spec/draft` is where all new work should take place. To publish a new version of the SLSA specification, copy the draft folder to a version specific folder (e.g., `spec/v1.1`) and make the necessary changes to that folder: it is possible for instance that not all that is in the draft should be included in which case you will need to remove that content, and several config and navigation files need to be updated such as:
+To patch a specific version of the specification, the changes should be made to both the corresponding branch as well as, if applicable, all the later versions and the draft on the main branch.
 
-```none
-_data/nav/config.yml
-_data/nav/v1.1.yml (corresponding to the version you are creating)
-_data/versions.yml
-_redirects
-```
+To compare the changes between two versions you may find it handy to use the [diff site script](https://github.com/slsa-framework/slsa/tree/main/www#comparing-built-versions).
+
+**Note**: When publishing new versions of the SLSA specification, make sure to follow the [Specification stages and versions documentation](www/spec-stages.md) and the [Specification Development Process](https://github.com/slsa-framework/governance/blob/main/5._Governance.md#4-specification-development-process) to ensure compliance with the [Community Specification License](https://github.com/slsa-framework/governance/blob/main/1._Community_Specification_License-v1.md).
+
+## Netlify and Jekylll
 
-To patch a specific version of the specification, the changes should be made to both the corresponding folder as well as, if applicable, to all later versions including the draft folder.
+The website https://slsa.dev is built with Jekyll and served by Netlify where we have an account managed by the Steering Committee. Netlify is setup to monitor the GitHub repository and automatically deploy updates when a PR is merged on main.
 
-Unfortunately we've not figured out a better way to handle the different versions with Jekyll. If you do, please let us know!
+The netlify configuration is in the `/netlify.toml` file. This file overrides settings defined on the Netlify admin control panel where we need to say little more than which repository and branch to monitor.
 
-To compare the changes between two versions you may find it handy to use the [diff site script](https://github.com/slsa-framework/slsa/tree/main/docs#comparing-built-versions).
+At deployment time, the website is built in several steps. First, we take all the different versions of the spec from the branches and copy them into corresponding `www/spec/<version>` folders. Then, the jekyll build is run to generate the website files in `www/_site` which is then deployed by netlify.
 
-**Note**: When publishing new versions of the SLSA specification, make sure to follow the [Specification stages and versions documentation](docs/spec-stages.md) and the [Specification Development Process](https://github.com/slsa-framework/governance/blob/main/5._Governance.md#4-specification-development-process) to ensure compliance with the [Community Specification License](https://github.com/slsa-framework/governance/blob/main/1._Community_Specification_License-v1.md).
+For more information see the [www/README.md](www/README.md) file.
 
 ## Workstream lifecycle
 

README.md

@@ -1,6 +1,6 @@
 # SLSA ("salsa") is Supply-chain Levels for Software Artifacts
 
-<img align="right" src="https://github.com/slsa-framework/slsa/blob/main/docs/images/slsa-dancing-goose-logo.svg" alt="The OpenSSF mascot, a goose in armor, strikes a pose wearing a red salsa dress">
+<img align="right" src="https://github.com/slsa-framework/slsa/blob/main/www/images/slsa-dancing-goose-logo.svg" alt="The OpenSSF mascot, a goose in armor, strikes a pose wearing a red salsa dress">
 
 SLSA (pronounced ["salsa"](https://www.google.com/search?q=how+to+pronounce+salsa)) is a security framework from source to service, giving anyone working with software a common language for increasing levels of software security and supply chain integrity. It’s how you get from safe enough to being as resilient as possible, at any link in the chain.
 
@@ -10,7 +10,7 @@ See https://slsa.dev to learn about SLSA.
 
 ## What's in this repo?
 
-The primary content of this repo is the [docs/](docs/) directory, which contains
+The primary content of this repo is the [www/](www/) directory, which contains
 the core SLSA specification and sources to the [slsa.dev] website. See the
 README.md in that directory for instructions on how to build the site.
 
@@ -40,7 +40,7 @@ See https://slsa.dev/community for ways to get involved in SLSA development.
 
 ## URL Aliases
 
-We have several [redirect](docs/_redirects) configured on slsa.dev for
+We have several [redirect](www/_redirects) configured on slsa.dev for
 convenience of the team:
 
 -   https://slsa.dev/gh &rArr; SLSA GitHub repo