nonspec: tooling for migration to a late-branching strategy, standardized devcontainers #1328

zachariahcox · 2025-04-20T14:08:15Z

fixes: #742

How to test:

Open this branch in a github codespace
Cd into the docs folder
run netlify dev
Open the browser and navigate to http://localhost:8888
Verify that the site is running locally

Development Environment Setup:

Added .devcontainer/devcontainer.json to configure a development container with Ruby 3.2, Jekyll, and Netlify CLI. It includes VS Code extensions for GitHub integration and sets up port forwarding for the Jekyll server.
Created .devcontainer/post-create.sh to automate gem installation, configure Bundler for local dependencies, and globally install the Netlify CLI.
Migrate tools to tools folder (from the root folder)
Propose script to perform late-branching refactor
Propose manual-dispatch workflow to execute the refactor when we're ready.
This change breaks our netlify preview buildsExplore a few optional workflow files to see how netlify preview builds could be supported. (for draft updates, it's easy, for release updates, what should happen?)
- No new automatic workflows should be added as a result of this PR.

Proposal for how to perform the late branch refactor

Added .github/workflows/migrate-to-late-branch.yml to enable manual migration to a late-branching strategy. The workflow runs a script to create version-specific branches from the main branch.
Added tools/migrate-to-late-branch.sh to automate the migration of spec versions to individual branches. The script creates a branch for each version, isolates the relevant files, and pushes the changes.

Proposal for changes to the devex

Added .github/workflows/netlify-preview.yml to deploy pull request previews to Netlify. The workflow builds the site using Jekyll and posts a comment with the preview link to the pull request.
Added .github/workflows/update-release.yml to create GitHub releases automatically when a releases/* branch is updated. This workflow is currently disabled.
Added tools/create-spec-release.sh to package the spec directory into a zip file, optionally generate an attestation, and create a GitHub release for the current branch.

Next steps:

After this PR, the plan would be to merge something like: nonspec: new website build strategy #1329

netlify · 2025-04-20T14:08:34Z

✅ Deploy Preview for slsa canceled.

Name	Link
🔨 Latest commit	`17076f7`
🔍 Latest deploy log	https://app.netlify.com/sites/slsa/deploys/680fbabb6e7daa0008fa1228

Copilot

Pull Request Overview

This pull request introduces several new GitHub workflows to support a migration toward a late-branching strategy and standardizes development containers.

Added a workflow to create a release on branch updates (currently disabled).
Introduced a Netlify preview deploy workflow (currently disabled).
Added a workflow for migrating to a late-branching strategy and updated the lint job to reference the new lint script location.

Reviewed Changes

Copilot reviewed 5 out of 9 changed files in this pull request and generated 1 comment.

File	Description
.github/workflows/update-release.yml	Adds a release creation workflow, disabled with an "if: false" flag.
.github/workflows/netlify-preview.yml	Introduces a Netlify preview deploy workflow, disabled by default.
.github/workflows/migrate-to-late-branch.yml	Adds a manually triggered migration workflow for late-branching.
.github/workflows/lint.yml	Updates the lint step to reference the script in the tools folder.

Files not reviewed (4)

.devcontainer/devcontainer.json: Language not supported
.devcontainer/post-create.sh: Language not supported
tools/create-spec-release.sh: Language not supported
tools/migrate-to-late-branch.sh: Language not supported

Comments suppressed due to low confidence (1)

.github/workflows/lint.yml:14

Verify that the new lint script path (./tools/lint.sh) is correct and that the script has executable permissions to prevent potential build failures.

- run: ./tools/lint.sh

.github/workflows/netlify-preview.yml

zachariahcox · 2025-04-20T14:15:29Z

The netlify failure is super confusing. I think it's fine -- this is technically nonspec and nothing should have changed.

10:08:38 AM: Failed during stage 'checking build content for changes': Canceled build due to no content change
10:08:38 AM: Custom publish path detected. Proceeding with the specified path: 'docs/_site'
10:08:38 AM: Custom build command detected. Proceeding with the specified command: 'bundle exec jekyll build --drafts --future'
10:08:38 AM: manpath: warning: $PATH not set
10:08:38 AM: No changes detected in base directory. Returning early from build.

zachariahcox · 2025-04-21T20:30:12Z

.github/workflows/update-release.yml

+          --title "Release $VERSION" \
+          --notes "Automated release from branch $GITHUB_REF" \
+          --repo "$GITHUB_REPOSITORY" \
+          --generate-notes || echo "Release already exists, skipping."


probably we'd want to delete and replace any existing releases when this happens?

Signed-off-by: Zachariah Cox <[email protected]>

Co-authored-by: Copilot <[email protected]> Signed-off-by: Zachariah Cox <[email protected]>

Signed-off-by: Zachariah Cox <[email protected]>

zachariahcox · 2025-04-21T20:31:36Z

.github/workflows/lint.yml

@@ -11,4 +11,4 @@ jobs:
      uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
    - run: npm ci --ignore-scripts
    - run: npm run lint --silent
-    - run: ./lint.sh
+    - run: ./tools/lint.sh


this just adapts to the relocated script.

zachariahcox · 2025-04-21T20:38:53Z

tools/create-spec-release.sh

+fi
+
+# --- Create a zip file of the spec directory ---
+zip -r spec.zip spec


this script won't work unless we've already migrated the repo. I can remove it from this PR if it's confusing.

zachariahcox · 2025-04-21T20:40:33Z

.github/workflows/netlify-preview.yml

+    types: [opened, synchronize, reopened]
+
+jobs:
+  if: false  # This disables the entire workflow


As discussed in the meeting today, it might make more sense for this to just happen on a daily schedule, only from the main branch, and only if there are published changes to releases (or the draft spec).

this workflow tries to do the right then whenever any PR is opened to any branch? complicated.
but it would be nice to keep the preview site feature if we can prevent it from being super difficult to maintain.

zachariahcox · 2025-04-21T20:42:01Z

.devcontainer/devcontainer.json

+        "github.copilot-chat", // Chat interface for GitHub Copilot
+        "github.github-vscode-theme", // GitHub's official VS Code theme
+        "github.vscode-github-actions", // GitHub Actions support
+        "github.vscode-pull-request-github" // GitHub Pull Requests and Issues


these are technically optional. I have no strong preference.

zachariahcox · 2025-04-21T20:44:06Z

.github/workflows/netlify-preview.yml

+        id: netlify_deploy
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}


I think we looked it up and we don't actually have these. Netlify is configured to pull automatically from the main branch via webhook. cc: @mlieberman85

Copilot

Pull Request Overview

This PR introduces tooling improvements to support a migration to a late-branching strategy, enhanced development environments via devcontainers, and experimental Netlify preview deployments.

Adds new devcontainer configurations and related scripts
Introduces three new CI workflows (release, late branching migration, and Netlify preview)
Updates lint workflow to reflect new script locations

Reviewed Changes

Copilot reviewed 5 out of 9 changed files in this pull request and generated 1 comment.

File	Description
.github/workflows/update-release.yml	Adds a GitHub release creation workflow (currently disabled)
.github/workflows/netlify-preview.yml	Introduces a Netlify deploy preview workflow (currently disabled), with a computed variable not used in the deploy command
.github/workflows/migrate-to-late-branch.yml	Adds a workflow to trigger the late-branching migration script manually
.github/workflows/lint.yml	Adjusts the lint script path

Files not reviewed (4)

.devcontainer/devcontainer.json: Language not supported
.devcontainer/post-create.sh: Language not supported
tools/create-spec-release.sh: Language not supported
tools/migrate-to-late-branch.sh: Language not supported

.github/workflows/netlify-preview.yml

lehors · 2025-04-22T13:49:10Z

tools/create-spec-release.sh

+if [[ "$PWD" != "$REPO_ROOT" ]]; then
+  echo "Error: Please run this script from the repository root: $REPO_ROOT"
+  exit 1
+fi


Can't you just start with cd "$REPO_ROOT" and be done?

that would probably work -- unclear if errors or fixes are better?

I generally find it annoying when a program tells me I should do something else rather than just doing it. I always think: "what don't you just do it if you know what needs to be done??"
You could print out a message explaining the change of current directory before doing it so that if anything goes wrong the user isn't left disoriented but that's all that's needed in my opinion.

Co-authored-by: Copilot <[email protected]> Signed-off-by: Zachariah Cox <[email protected]>

zachariahcox · 2025-04-28T17:31:46Z

per discussion today, I think we want to close this PR.

We will

setup a new repo "slsa-www?"
clone this repo to that one
in the www repo, delete "everything that is not website related
in this (the "spec") repo, delete everything that is not content-related
disconnect the automatic netlify deployment and move it to the www repo
perform a late branch migration for the spec folder
produce release branches and artifacts for all old versions of the spec. the main branch should track the current working draft.

lehors · 2025-04-28T18:45:55Z

* setup a new repo "slsa-www?"

Given that the website is slsa.dev, should we use that name? It doesn't really matter, just a thought.

zachariahcox added 13 commits April 19, 2025 13:04

scripts

cd73218

chmod

c68e7fb

cleanup

794eaf8

script corrections and cleanup

c72bbfe

add devcontainer

7fca466

try to use actions instead of apps

f5867a2

beefing up scripts

b08a8e8

cleanup

48e4c4e

cleanup comments

d9350d2

testing

a048784

make it so!

1d317d3

clean up for review

279b752

consolidate tools, disable workflow files

6806635

github-project-automation bot added this to Issue triage Apr 20, 2025

github-project-automation bot moved this to 🆕 New in Issue triage Apr 20, 2025

zachariahcox requested review from lehors and Copilot April 20, 2025 14:08

Copilot AI reviewed Apr 20, 2025

View reviewed changes

.github/workflows/netlify-preview.yml Outdated Show resolved Hide resolved

zachariahcox mentioned this pull request Apr 20, 2025

nonspec: new website build strategy #1329

Draft

zachariahcox requested review from a team April 21, 2025 16:31

zachariahcox commented Apr 21, 2025

View reviewed changes

zachariahcox and others added 3 commits April 21, 2025 13:37

Update migrate-to-late-branch.sh

a42a389

Signed-off-by: Zachariah Cox <[email protected]>

Update .github/workflows/netlify-preview.yml

f0b0f8a

Co-authored-by: Copilot <[email protected]> Signed-off-by: Zachariah Cox <[email protected]>

Update migrate-to-late-branch.yml

dbdfb90

Signed-off-by: Zachariah Cox <[email protected]>

zachariahcox commented Apr 21, 2025

View reviewed changes

zachariahcox requested a review from Copilot April 21, 2025 20:44

Copilot AI reviewed Apr 21, 2025

View reviewed changes

.github/workflows/netlify-preview.yml Outdated Show resolved Hide resolved

lehors reviewed Apr 22, 2025

View reviewed changes

zachariahcox and others added 2 commits April 28, 2025 17:25

typo

ad8c796

Update .github/workflows/netlify-preview.yml

17076f7

Co-authored-by: Copilot <[email protected]> Signed-off-by: Zachariah Cox <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

nonspec: tooling for migration to a late-branching strategy, standardized devcontainers #1328

nonspec: tooling for migration to a late-branching strategy, standardized devcontainers #1328

zachariahcox commented Apr 20, 2025 •

edited

Loading

netlify bot commented Apr 20, 2025 •

edited

Loading

Copilot AI left a comment

zachariahcox commented Apr 20, 2025

zachariahcox Apr 21, 2025

zachariahcox Apr 21, 2025

zachariahcox Apr 21, 2025

zachariahcox Apr 21, 2025

zachariahcox Apr 21, 2025

zachariahcox Apr 21, 2025

Copilot AI left a comment

lehors Apr 22, 2025

zachariahcox Apr 28, 2025

lehors Apr 28, 2025

zachariahcox commented Apr 28, 2025 •

edited

Loading

lehors commented Apr 28, 2025

nonspec: tooling for migration to a late-branching strategy, standardized devcontainers #1328

Are you sure you want to change the base?

nonspec: tooling for migration to a late-branching strategy, standardized devcontainers #1328

Conversation

zachariahcox commented Apr 20, 2025 • edited Loading

Development Environment Setup:

Proposal for how to perform the late branch refactor

Proposal for changes to the devex

Next steps:

netlify bot commented Apr 20, 2025 • edited Loading

✅ Deploy Preview for slsa canceled.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

zachariahcox commented Apr 20, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zachariahcox commented Apr 28, 2025 • edited Loading

lehors commented Apr 28, 2025

zachariahcox commented Apr 20, 2025 •

edited

Loading

netlify bot commented Apr 20, 2025 •

edited

Loading

zachariahcox commented Apr 28, 2025 •

edited

Loading