Developer Dependency & Upgrade Runbook

Maintaining package version parity and monorepo build synchronization is essential for stable development. This runbook details how to upgrade core Framework M dependencies, manage pnpm workspace version pins, and verify changes across our modular application stack.

1. Upstream Python Dependencies (uv)

Business M manages Python packaging constraints using editable workspace declarations and uv locking mechanisms.

1.1 Checking version history

To identify the latest releases of the core framework libraries from the active registry:

pip index versions framework-m
pip index versions framework-m-core
pip index versions framework-m-studio

1.2 Upgrading version floors

Dependencies are managed using floor version configurations in each package’s pyproject.toml file (e.g. libs/finance/pyproject.toml).

Open the target pyproject.toml file.

Update the constraint in the dependencies block:

dependencies = [
    "framework-m>=0.10.2",
]

Execute a workspace-wide lock file recalculation from the monorepo root:
Terminal window
```
uv sync --upgrade
```
This syncs the workspace-level uv.lock file and upgrades your active virtual environment.

2. Frontend & Monorepo Package Alignment (pnpm)

Our frontend components use pnpm workspaces for local dependency linking. To ensure stable runtime behavior, explicit versions are pinned using workspace qualifiers.

2.1 Preserving Workspace Version Pins

During recursive package upgrades (e.g., running pnpm update), pnpm may canonicalize explicit local package mappings (e.g. changing "@business-m/finance": "workspace:^0.10.0" to generic protocols like "workspace:^").

To prevent protocol stripping and lock versions securely:

The CLI Sync Tool (deps.py): Always run our specialized dependency tool to automate package JSON backups and restore explicit version pinning:
Terminal window
```
python deps.py sync --preserve-versions
```
This utility parses workspace configurations, backs up explicitly versioned references, initiates pnpm recursive update, and instantly restores pinned protocols to prevent build breaks in the CI/CD pipeline.

2.2 Global Override Anchors

For shared UI primitives, centralize package dependency locks inside the root package.json overrides:

"pnpm": {
  "overrides": {
    "@framework-m/ui": "0.7.8",
    "@framework-m/plugin-sdk": "0.6.2"
  }
}

Apply the overrides using:

pnpm install

3. Database Migration Procedures

Core framework updates may introduce schema enhancements to standard, built-in DocTypes.

Navigate to the main application directory:
Terminal window
```
cd apps/business-m
```
Trigger dry-run audits to inspect model differences before database execution:
Terminal window
```
uv run m migrate plan --apps business_m
```
Synchronize the PostgreSQL schemas:
Terminal window
```
uv run m migrate sync --apps business_m
```

4. Verification & QA Checks

To guarantee zero-regression upgrades, complete this three-step verification loop:

Step 1: Run Workspace Unit Tests

Verify all sub-library controller and model tests run successfully:

uv run pytest

Step 2: Test Frontend Compilation

Confirm that Vite module federation and Tamagui asset compilation passes across all applications:

pnpm -r build

Step 3: Clear Module Federation Caches

If remote MFEs load stale UI fragments in the browser after upgrading, clean your browser storage and wipe your local Vite cache directory:

rm -rf node_modules/.vite
pnpm install