From 8ceee9b652eb9fb3852417ca9b0c129d4f31e961 Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Fri, 5 Jun 2026 12:57:30 -0400 Subject: [PATCH] docs: replace frozen 'blessed version' with automated pin-currency policy Exact pins remain (reproducibility) but the pinned version is kept current by Dependabot version updates gated by CI + dependency review, not by a number frozen in the handbook. Blanket dependabot ignore entries are banned; version-specific ignores only, commented and temporary. Bundled-dep vulnerabilities are a prompt to advance the pin, never to dismiss the alert. --- aws-infrastructure.md | 8 ++++++-- cdk-project-layout.md | 6 +++--- github-standards.md | 8 ++++++++ 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/aws-infrastructure.md b/aws-infrastructure.md index 8d76ad0..adbc4ff 100644 --- a/aws-infrastructure.md +++ b/aws-infrastructure.md @@ -22,9 +22,13 @@ Never rely on the CloudWatch default for log retention. Always set `RetentionInD ## CDK Version Policy -Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.257.0**. +Pin `aws-cdk-lib` to an exact version (no `^`, `~`, or `>=`) and let Dependabot keep it current. There is no static "blessed version" — the org standard is the latest release that passes the gates below. Do not add blanket `dependabot.yml` ignore entries for `aws-cdk-lib`; that is how pins rot into carrying known vulnerabilities. -Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors, and bundled deps can carry vulnerabilities that npm `overrides` cannot fix (e.g., 2.253.1 bundled a high-severity-vulnerable fast-uri; the only remedy is moving to a release that bundles the patched version). When bumping the blessed version: test `npm ci` locally and confirm the new release's bundled deps clear dependency review. +Why exact + automated: the exact pin plus the lockfile gives reproducible builds; weekly Dependabot version updates keep the pin moving; CI (`npm ci` + `cdk synth`) and the dependency-review check reject a bad release at the PR. A release with broken bundled-dep metadata (e.g. 2.254.0) fails `npm ci` on its own bump PR; a release bundling a vulnerable transitive dep fails dependency review. Either way, a bad release never merges — the gates do the vetting, not a frozen number in this document. + +aws-cdk-lib bundles transitive dependencies (`inBundle: true`) that npm `overrides` cannot patch. When a bundled dep has a vulnerability, the only fix is advancing to a release that bundles the patched version — treat the alert as a prompt to merge the next Dependabot bump, never as something to dismiss indefinitely. + +If a specific release is known-bad, ignore that version only (`ignore: - dependency-name: aws-cdk-lib, versions: ["2.254.0"]`) with a comment explaining why, and remove the entry once a fixed release ships. When upgrading, verify on a branch first: 1. Update `package.json` to the new version diff --git a/cdk-project-layout.md b/cdk-project-layout.md index 484c708..6945fc8 100644 --- a/cdk-project-layout.md +++ b/cdk-project-layout.md @@ -83,16 +83,16 @@ A handful of stacks predate this convention and remain PascalCase (e.g., `SeaHav ## Version Pinning -Pin `aws-cdk-lib` to the blessed version: **2.257.0**. +Pin `aws-cdk-lib` to an exact version (no `^`/`~`/`>=`) and let Dependabot keep it current — no blanket ignore entries. See [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy) for the full policy. -`aws-cdk-lib` bundles transitive dependencies (`inBundle: true`). Certain versions break `npm ci` with phantom missing-package errors that cannot be fixed via npm `overrides`. Always test before bumping: +`aws-cdk-lib` bundles transitive dependencies (`inBundle: true`). Certain versions break `npm ci` with phantom missing-package errors that cannot be fixed via npm `overrides`. CI gates Dependabot bumps automatically; when bumping manually, test first: 1. Update `package.json` to the new version 2. Run `rm -rf node_modules package-lock.json && npm install` 3. Run `npm ci` -- if it fails, the version is not safe 4. Run `npx cdk synth` -- if it fails, the version is not safe -Dependabot will flag vulnerabilities in bundled transitive deps. Dismiss these alerts with **"waiting for upstream fix"** -- there is no action available until `aws-cdk-lib` publishes a patched release. +Dependabot will flag vulnerabilities in bundled transitive deps. npm `overrides` cannot fix these — the remedy is advancing to the release that bundles the patched version. Merge the next `aws-cdk-lib` bump rather than dismissing the alert. See [aws-infrastructure.md](aws-infrastructure.md#cdk-version-policy) for more detail. diff --git a/github-standards.md b/github-standards.md index 6ceccda..adf9feb 100644 --- a/github-standards.md +++ b/github-standards.md @@ -13,6 +13,14 @@ Every active repo with package dependencies must have a `.github/dependabot.yml` that covers all relevant ecosystems. +### Pinning Principle + +Exact pins are for reproducibility, not for freezing time. The pinned version is kept current by Dependabot version updates gated by CI and dependency review — never by a version number written in documentation. + +- Never add a blanket `ignore` entry for a dependency. If a specific release is broken, ignore that release only (`versions: ["x.y.z"]`), with a comment, and remove the entry once a fixed release ships. +- Never dismiss a vulnerability alert as "waiting for upstream" without a linked follow-up that advances the pin when the fix ships. +- If a bump PR fails CI, the gate worked — leave the bad release unmerged and take the next one. + ### Ecosystem Selection Choose ecosystems based on what dependency files exist in the repo: