From 42791c1b5c20edc3d18547b29fe7d894ff93972a Mon Sep 17 00:00:00 2001 From: abosio Date: Thu, 16 Apr 2026 10:25:24 -0400 Subject: [PATCH 1/3] docs(adr): add version pinning strategy ADR and link from README Co-Authored-By: Claude Sonnet 4.6 --- .github/README.md | 4 +++ docs/adr/README.md | 15 ++++++++++ docs/adr/decisions/.gitkeep | 0 .../2026-04-16-version-pinning-strategy.md | 28 +++++++++++++++++++ 4 files changed, 47 insertions(+) create mode 100644 docs/adr/README.md create mode 100644 docs/adr/decisions/.gitkeep create mode 100644 docs/adr/proposals/2026-04-16-version-pinning-strategy.md diff --git a/.github/README.md b/.github/README.md index 84e6515..a12b0e3 100644 --- a/.github/README.md +++ b/.github/README.md @@ -53,3 +53,7 @@ answer all the questions, and you'll have your new project! Inside `myproject/README.md`, you will have more documentation explaining how to use and configure your newly created project. + +## Architecture Decision Records + +Technical decisions for this project are documented in [`docs/adr/`](../docs/adr/README.md). diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..f7d2090 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,15 @@ +# Technical Decision Logs + +Each file referenced here contains decisions for this project. + +Each decision log includes: +- Date of decision +- Decision title/summary +- Context and rationale +- Impact and next steps + +## Decision Index + +## Proposal Index + +- 2026-04-16: [Version Pinning Strategy](proposals/2026-04-16-version-pinning-strategy.md) diff --git a/docs/adr/decisions/.gitkeep b/docs/adr/decisions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/adr/proposals/2026-04-16-version-pinning-strategy.md b/docs/adr/proposals/2026-04-16-version-pinning-strategy.md new file mode 100644 index 0000000..7bf68f5 --- /dev/null +++ b/docs/adr/proposals/2026-04-16-version-pinning-strategy.md @@ -0,0 +1,28 @@ +## 2026-04-16 - Version Pinning Strategy + +### Decision + +Reintroduce version pinning for the Full Stack template. CI will generate and store tested lock files weekly, and SCAF will fetch these pinned artifacts during bootstrap instead of resolving dependencies live. + +### Context & Rationale + +The Full Stack template previously generated dependencies on the fly during bootstrap, risking broken builds from untested upstream package changes outside the team's direct control. This "bleeding edge" approach — always pulling the latest available packages — introduced unpredictable breakage for users bootstrapping new projects. + +The team evaluated two approaches: + +- **Unpinned (status quo):** Dependencies resolved at bootstrap time. Always fresh, but fragile — any upstream package change can silently break the bootstrap experience. +- **Pinned with CI-driven updates ("cutting edge"):** Lock files generated from a known-working CI run and stored as artifacts. SCAF fetches these during bootstrap. Weekly CI runs regenerate and commit updated lock files, keeping the template current without exposing users to unverified upstream changes. + +The team agreed that pinning with automated updates is the industry-standard approach and resolves the majority of existing bootstrap reliability issues. Because automated tests gate all lock file updates, manual PR review of weekly dependency updates is unnecessary — a failed CI run will block the update from landing. + +The main branch remains protected by mandatory PR CI gating, ensuring it stays releasable. However, dependency breakage from packages outside the repo is best mitigated by pinned lock files from successful CI runs rather than relying on main's recency. + +### Impact & Next Steps + +- Bootstrap reliability improves significantly: users get a dependency set known to work, not the latest unverified packages. +- Bootstrap time may also improve, as preresolved lock files reduce install-time resolution overhead. +- Weekly automated CI workflow to regenerate and commit updated lock files; no manual PR review required given test coverage. +- Dependabot PRs (currently paused) will resume with CI gating to keep CI tooling dependencies current. +- SCAF to be updated to fetch pinned lock file artifacts during bootstrap instead of resolving dependencies live. +- SCAF UI to be enhanced to allow users to select a specific release or opt into main explicitly, improving transparency and control. +- Offline bootstrap remains unsupported by design; SCAF requires online access to fetch templates and artifacts. From 1bb205fdf4332680c5e7f7ab43625f3e4b818f00 Mon Sep 17 00:00:00 2001 From: abosio Date: Thu, 16 Apr 2026 10:27:16 -0400 Subject: [PATCH 2/3] fix: rename .gitkeep to .gitignore --- docs/adr/decisions/{.gitkeep => .gitignore} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/adr/decisions/{.gitkeep => .gitignore} (100%) diff --git a/docs/adr/decisions/.gitkeep b/docs/adr/decisions/.gitignore similarity index 100% rename from docs/adr/decisions/.gitkeep rename to docs/adr/decisions/.gitignore From 4cded1ce407f22c491296837a6ad92953ee8e855 Mon Sep 17 00:00:00 2001 From: abosio Date: Thu, 16 Apr 2026 10:32:17 -0400 Subject: [PATCH 3/3] docs(adr): mention packages in offline bootstrap reference --- docs/adr/proposals/2026-04-16-version-pinning-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/proposals/2026-04-16-version-pinning-strategy.md b/docs/adr/proposals/2026-04-16-version-pinning-strategy.md index 7bf68f5..e9934cc 100644 --- a/docs/adr/proposals/2026-04-16-version-pinning-strategy.md +++ b/docs/adr/proposals/2026-04-16-version-pinning-strategy.md @@ -25,4 +25,4 @@ The main branch remains protected by mandatory PR CI gating, ensuring it stays r - Dependabot PRs (currently paused) will resume with CI gating to keep CI tooling dependencies current. - SCAF to be updated to fetch pinned lock file artifacts during bootstrap instead of resolving dependencies live. - SCAF UI to be enhanced to allow users to select a specific release or opt into main explicitly, improving transparency and control. -- Offline bootstrap remains unsupported by design; SCAF requires online access to fetch templates and artifacts. +- Offline bootstrap remains unsupported by design; SCAF requires online access to fetch templates, artifacts and packages.