From 07972d699e0a0ea427480a0fcccf08b32638546e Mon Sep 17 00:00:00 2001 From: tinkeragora <314183062+tinkeragora@users.noreply.github.com> Date: Fri, 14 Aug 2026 05:26:03 +0800 Subject: [PATCH] docs: define dependency upgrade review gates --- CHANGELOG.md | 3 +++ docs/SECURITY_OPERATIONS.md | 2 +- docs/WORKFLOWS.md | 39 +++++++++++++++++++++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fff9824..3287360 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,9 @@ when releases begin. ### Changed +- Documented dependency-update review gates: Dependabot is proposal-only, + patch/minor groups use full checks, and coupled Rust major upgrades require a + coordinated migration with dependency-graph and compatibility evidence. - Registered Data Toolbox and JSON YAML Swiss in the public settings policy, synchronized PE Version Info's `v0.1.0-alpha.1` release, and enabled the missing JSON YAML Swiss secret-scanning controls. diff --git a/docs/SECURITY_OPERATIONS.md b/docs/SECURITY_OPERATIONS.md index 36bee6a..0a4a21a 100644 --- a/docs/SECURITY_OPERATIONS.md +++ b/docs/SECURITY_OPERATIONS.md @@ -14,7 +14,7 @@ manual because an API setting alone cannot prove them. | Confidential contact | No private security email or other verified intake channel is published | Publish only a controlled, monitored confidential channel | Ownership, access, retention, handoff, and abuse handling are verified and publication is explicitly authorized | | Conduct-reporting channel | No verified private conduct-reporting channel is published | Maintain a controlled private channel separate from vulnerability reporting | Ownership, least-privilege access, retention, handoff, reporter flow, and moderator responsibility are verified before Issues, contribution solicitation, Discussions, or Code of Conduct enforcement | | New-repository defaults | Dependency graph, Dependabot alerts and security updates, secret scanning, and push protection are enabled for newly created repositories | Keep all five defaults enabled and audit every published repository after creation | GitHub changes a capability, a repository requires a documented exception, or the read-only audit reports drift | -| Dependency alerts and updates | Organization defaults protect new repositories; every published repository is still checked independently because defaults do not repair older repositories | Enable and verify per published repository with narrowly scoped update pull requests | Manifests are accurate, a maintainer can triage findings, and feature availability is confirmed | +| Dependency alerts and updates | Organization defaults protect new repositories; every published repository is still checked independently because defaults do not repair older repositories. Dependabot proposes bounded patch/minor groups and isolated major migrations; it does not merge changes | Enable and verify per published repository with narrowly scoped update pull requests; stop on failed required checks and review Rust ecosystem-coupled upgrades as one migration | Manifests are accurate, a maintainer can triage findings, MSRV and supported targets are tested, and feature availability is confirmed | | Secret scanning and push protection | Enabled for `.github` | Keep enabled on public repositories and verify bypass and alert handling | Availability is confirmed, bypass responsibility is defined, and test behavior is understood | | Code scanning | No scan is claimed as configured | Add project-appropriate analysis with reviewed queries and actionable ownership | The project builds reliably, scan permissions are minimal, results are triaged, and the workflow is explicitly authorized | | Security roles | Closed `security` Team exists, is the organization security manager, has `write` on `.github`, and currently contains only `tinkeragora` | Add qualified independent people with least privilege; keep recovery separate from the sole operator | A second independent trusted owner and qualified maintainers exist, Team membership is verified, and access is explicitly authorized | diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md index 9cdb917..125e745 100644 --- a/docs/WORKFLOWS.md +++ b/docs/WORKFLOWS.md @@ -191,6 +191,33 @@ updates remain eligible for immediate pull requests and are not delayed by the cooldown. Repositories with extra Cargo workspaces or worker manifests may add separate entries with a documented directory rationale. +Dependabot is a change proposal generator, not an auto-merge authority. A +passing check is necessary but does not authorize merging a dependency update. +Review the manifest and lockfile diff, upstream release notes, license and +advisory state, MSRV, supported targets, and the repository's public contract. +Keep a PR open only while it is actionable; close or regenerate stale PRs whose +base branch is no longer current. + +For Rust updates, treat a major or ecosystem-coupled change as a migration. +Before editing application code, inspect the dependency graph with +`cargo tree -d` and `cargo tree -i `, identify duplicate `digest`, +`rand_core`, or other trait ecosystems, and decide whether the whole group can +move together. HMAC/hash/RSA changes must be tested as one compatibility unit; +do not merge a standalone `sha2`, `hmac`, or `rand` PR when the existing source +still uses the old API. A failed required check is a hard stop, not a reason to +lower lint levels, skip tests, or merge the lockfile manually. The migration PR +must include outcome-focused tests for native, WASM, MSRV, and platform-specific +paths that the dependency can affect. + +For patch and minor updates, prefer the configured ecosystem group, then run +the complete repository checks with the updated lockfile. For major updates, +keep the PR separate unless a reviewed migration plan explicitly combines the +required packages. Record intentional deferrals with the package, current +version, affected contract or platform, and a re-review trigger; never use a +permanent Dependabot ignore as a substitute for that decision. A repository +must have no unresolved failed dependency PRs at release time unless the +release checklist records their scope and rationale. + The organization audit treats missing, untracked, or divergent Dependabot configuration as drift. A project must not claim a complete supply-chain gate until its manifest directories, lockfiles, update groups, cooldown, and PR @@ -222,6 +249,18 @@ documents that cooldown applies only to version updates, not security updates, so a security update is not delayed by this window. See the official [Dependabot options reference](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#cooldown-). +The minimum review record for a dependency PR is: + +1. Current base branch and exact head commit are verified. +2. The manifest, lockfile, upstream release notes, MSRV, license, and advisory + impact are reviewed. +3. Native, WASM, MSRV, browser, and platform checks relevant to the repository + are green on the current base. +4. Major or coupled Rust updates include a migration note and compatibility + tests; failed checks remain unmerged. +5. The merge is squash-only on `main`, and the release changelog records a + user-visible or security-relevant dependency change. + Run the repository-owned checks locally with: ```console