Skip to main content

[DRAFT] ADR-008: Package Version Locking Strategy

Context​

In a documentation portal using Docusaurus and potentially other Node.js tools, the consistency of the build environment is critical. Minor or patch updates in dependencies can break the build or change UI behavior unexpectedly, especially when agents are performing bulk modifications.

Proposed Decision​

We propose to strictly lock versions in package.json and enforce the commitment of package-lock.json to the repository.

  1. Use exact versions instead of ranges (e.g., 1.2.3 instead of ^1.2.3).
  2. Run npm ci in CI/CD environments to ensure identical installs.
  3. Only update dependencies via a dedicated ADR-backed task.

Expected Consequences​

  • Positive: Deterministic builds, elimination of "it works on my machine" issues, and safe environment for AI agents.
  • Negative: Requires more manual effort to keep dependencies updated and secure.