Skip to main content

Dependency Maintenance Policy

Framework M follows a Local-First dependency maintenance strategy. This approach ensures maximum sovereignty by leveraging built-in CLI tools (uv, pnpm) already present in the development environment, avoiding any third-party subscriptions or external services.

1. Audit vs. Upgrade​

It is critical to distinguish between Security Auditing and Dependency Upgrading:

  • Security Auditing: Checking for known vulnerabilities (CVEs) in your current dependency tree. This is automated in the CI pipeline.
  • Dependency Upgrading: Proactively checking for new versions (patches, minors, majors) that offer performance boosts, bug fixes, or new features. This is a manual developer routine.

2. Maintenance Tiers​

Update TierFrequencyStrategy
Security PatchesImmediateApply as soon as audit fails or a CVE is announced.
Patch & MinorMonthlyBatch and apply updates to benefit from stability and performance.
MajorAs NeededRequires explicit architectural review before upgrading.

3. Python Workflow (uv)​

Python dependencies are managed via uv. The uv.lock file ensures reproducible builds.

Discovery​

Run this command to see what can be upgraded without a full re-lock:

uv lock --upgrade --dry-run

Applying Updates​

To upgrade all packages to their latest allowed versions in pyproject.toml:

uv lock --upgrade
uv sync

To upgrade a specific package​

uv add "package-name@latest"

4. Node.js Workflow (pnpm)​

Frontend and JS utilities are managed via pnpm workspaces.

Discovery​

Run this command from the root to see outdated packages across all apps and libs:

pnpm outdated -r

Applying Updates​

To update packages interactively:

pnpm update -i -r

Or to update to the latest compatible versions automatically:

pnpm update -r

5. Security Checklist​

Always run the local audit tools before committing dependency updates:

# Python
uv run --with pip-audit pip-audit

# Node.js
pnpm audit

6. GitLab CI Maintenance Pipeline​

A dedicated CI job is available for automated checking without running the full test/build suite.

Manual Trigger​

To run a dependency check manually:

  1. Go to Build > Pipelines in GitLab.
  2. Click Run pipeline.
  3. Select the branch (e.g., main).
  4. Add a variable: Key: CHECK_DEPENDENCIES, Value: true.
  5. Click Run pipeline.

This will trigger the dependency-maintenance job.

Scheduled Checks​

A pipeline schedule should be configured (e.g., weekly) to run this job automatically. This will generate actual Merge Requests in GitLab for available upgrades, providing a proactive "Dependabot-like" experience. Developers only need to review, test, and merge the generated MRs.

CI Scoping​

The maintenance pipeline is isolated such that:

  • It runs the create_dependency_mr.py script.
  • It identifies all outdated dependencies across uv (Python) and pnpm (Node).
  • It automatically creates a dedicated Merge Request for each package, allowing for isolated testing and granular merging.
  • Reports and logs are available in the job artifacts for 1 week.