Build dependency management

Build and Dependency Management

How a project declares versions, shares build logic, and admits new dependencies. The cross-cutting principles hub is the coding-standards skill; this skill is the build-layer detail.

---

When to activate

• Adding, upgrading, or removing a dependency.
• Setting up or refactoring build files for a new module or project.
• Centralising versions or build configuration across a multi-module repository.
• Reviewing a change that touches build or dependency files.

---

One version catalog per project

• Keep all dependency versions in one central place: a single version catalog in a TOML file (for example a Gradle libs.versions.toml, or the equivalent lock and manifest pair for the language).
• Never hardcode a version string inside an individual module. A module references the catalog entry; the version lives in one place so a bump is one edit.
• Pin versions so installs are reproducible. Commit the lockfile. An unpinned range turns a clean checkout into a different build tomorrow.

---

Lean on a bill of materials

• Manage versions through a bill of materials wherever one exists, and import it rather than pinning the versions it already governs.
• Lean on a bill of materials as much as possible so a whole family of libraries moves together and stays mutually compatible. Pinning one member of a managed family by hand is how version-skew bugs start.

---

Share build configuration

• Share common build configuration in one place (a convention plugin, a shared build file, a parent definition) rather than repeating it in every module. Repetition across module build files drifts the same way duplicated code does.
• Keep the build itself readable. A build file is code; the naming, structure, and DRY rules apply to it too.

---

Admit dependencies deliberately

• Justify every new dependency before adding it, and ask first. A dependency is a permanent maintenance and security liability, not a free function.
• Prefer the standard library and boring, well-understood dependencies over novelty. The exciting library is the one that is abandoned in two years.
• Honor any explicit list of allowed or forbidden libraries for the project, including license constraints (for example forbidding copyleft licenses in distributed code).
• Review and update dependencies on a schedule, with a vulnerability scan, but never through an automatic trigger. Enabling a self-scanning bot or auto-merging a dependency bump is an approval-gated decision, not a default.

---

Generated sources

Never commit generated sources or build output. Regenerate them from their source, and never hand-edit a generated file; change the input and run the generator. A generated file checked into version control drifts from its source the first time someone edits it by hand.