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. Automated Maintenance with m deps​

Framework M Studio provides the m deps CLI command suite to automate dependency auditing and multi-package upgrades.

Checking Outdated Dependencies​

To inspect dependencies across the project:

# Check all package managers (uv and pnpm)
uv run m deps check

# Check only Python dependencies
uv run m deps check --manager uv

# Check only Node/Frontend dependencies
uv run m deps check --manager pnpm

# Output machine-readable JSON
uv run m deps check --json

Upgrading Dependencies​

m deps upgrade automates the update process, handles workspace package references, commits changes, and opens a Merge Request:

# Upgrade all dependencies across both uv and pnpm
uv run m deps upgrade --manager all

# Upgrade a single package
uv run m deps upgrade pydantic --manager uv

# Perform a dry-run (preview changes without branch/commit/MR)
uv run m deps upgrade --dry-run

# Update dependencies directly in working tree without creating a branch
uv run m deps upgrade --skip-branch

# Upgrade to latest available versions (including majors)
uv run m deps upgrade --latest

Options for m deps upgrade:

  • package: Target package name (omit or use all to upgrade all dependencies).
  • --manager <uv|pnpm|all>: Target package manager (default: uv).
  • --provider <gitlab|github>: Git provider for automated MR/PR creation (default: gitlab).
  • --token <TOKEN>: Git provider access token (defaults to environment variables GITLAB_TOKEN, GITHUB_TOKEN, or M_CI_TOKEN).
  • --project-id <ID>: GitLab project ID or GitHub owner/repo.
  • --latest: When set, allows breaking/major updates (pnpm update -r --latest / uvx uv-upx).
  • --dry-run: Preview without altering branch or opening MR.
  • --skip-branch: Update lockfiles without creating a git branch.
  • --root <PATH>: Path to project root.

7. 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 m deps upgrade --manager all.
  • It identifies all outdated dependencies across uv (Python) and pnpm (Node).
  • It creates a dedicated Merge Request tracking the updates.
  • Reports and logs are available in the job artifacts for 1 week.