Dependency Pinning & Versioning¶

Status: 🟢 Active  |  Owner: Engineering Enablement  |  Last Reviewed: 2025-Q4

Overview¶

Dependency versioning discipline is the difference between builds that are reproducible and builds that are unpredictable. An unpinned dependency can change between two builds of the same commit — introducing bugs, security vulnerabilities, or breaking changes without any code change. All production services must produce identical builds from identical source regardless of when or where the build runs.

Pinning Requirements¶

Lock Files Are Mandatory¶

Every project must commit its lock file to version control. Lock files record the exact resolved versions of all direct and transitive dependencies.

package-lock.json / pnpm-lock.yaml must be committed to version control. Entries in .gitignore that exclude lock files are prohibited.

Direct Dependency Version Specification¶

Transitive Dependencies¶

Lock files handle transitive dependency pinning automatically. Do not manually pin transitive dependencies in your manifest file — let the lock file handle them. Manual transitive dependency pinning creates maintenance burden and can block security updates.

Version Upgrade Strategy¶

Automated Updates with Dependabot / Renovate¶

All repositories must enable Dependabot (GitHub) or Renovate for automated dependency update PRs. These tools: - Open PRs with dependency updates as they are released. - Include vulnerability information when updates patch a CVE. - Can be configured for update frequency and grouping.

Required configuration:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    groups:
      spring-boot:
        patterns:
          - "org.springframework.boot:*"

  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      minor-and-patch:
        update-types:
          - "minor"
          - "patch"

Manual Upgrade Cadence¶

In addition to automated updates, all dependencies should be reviewed and upgraded quarterly as part of planned maintenance work. The process:

1. Run npm outdated, pip list --outdated, mvn versions:display-dependency-updates (as applicable).
2. Group updates by risk level: patch (low) → minor (medium) → major (high).
3. Upgrade patch and minor versions as a batch with full test suite validation.
4. Upgrade major versions individually, reviewing changelog and migration guide for each.

Major Version Upgrades¶

Major version upgrades often contain breaking changes and require: - Reading the full changelog and migration guide. - Updating the team in a PR description with a summary of breaking changes. - Running the full test suite including integration and E2E tests. - If the upgrade affects a public API or service interface, following the Deprecation & Sunsetting Policy.

Semantic Versioning (SemVer)¶

All internal libraries and services follow Semantic Versioning:

MAJOR.MINOR.PATCH  (e.g., 3.14.2)

Pre-release Versions¶

• SNAPSHOT versions (Java Maven): For internal development builds. Never use SNAPSHOT dependencies in production builds.
• alpha, beta, rc pre-releases: Permitted in development and staging. Not permitted in production without explicit Architecture Team approval.

Dependency Vulnerability SLA¶

When a vulnerability is discovered in a dependency:

See Vulnerability Scanning for tooling and process details.

References¶

• Package & Library Approval
• Vulnerability Scanning
• License Compliance

Last reviewed: 2025-Q4  |  Owner: Engineering Enablement