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)
Section titled “1. Upstream Python Dependencies (uv)”Business M manages Python packaging constraints using editable workspace declarations and uv locking mechanisms.
1.1 Checking version history
Section titled “1.1 Checking version history”To identify the latest releases of the core framework libraries from the active registry:
pip index versions framework-mpip index versions framework-m-corepip index versions framework-m-studio1.2 Upgrading version floors
Section titled “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.tomlfile. - Update the constraint in the dependencies block:
dependencies = ["framework-m>=0.10.2",]
- Execute a workspace-wide lock file recalculation from the monorepo root:
This syncs the workspace-level
Terminal window uv sync --upgradeuv.lockfile and upgrades your active virtual environment.
2. Frontend & Monorepo Package Alignment (pnpm)
Section titled “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
Section titled “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
Section titled “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 install3. Database Migration Procedures
Section titled “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
3.1 Upgrade notes: invoice ledger posting
Section titled “3.1 Upgrade notes: invoice ledger posting”Releases that include invoice GL posting add columns and statuses; no hand-written migration is required, but follow these steps:
- Apply the schema with
uv run m migrate all --apps business_m,wms,m_pos,finance(runs versioned patches, then the declarative sync). The Compose and Helm migration jobs currently callm migrate sync, which is equivalent while the repository has no Alembic patches; switch them tom migrate allbefore the first patch is added. - In Finance Settings, set
default_receivable_accountanddefault_payable_account, anddefault_income_account/default_expense_accountif items and parties do not name their own accounts. Until they are set, submitting an invoice is refused with a message naming the missing setting. - Make sure every default Tax Template item has an account. A tax row with an amount and no account blocks submit.
- Invoices created programmatically (for example from a delivery or a receipt) have no company. On a single-company site it is filled in at submit; on a multi-company site set it before submitting.
- Invoices submitted before the upgrade are already Submitted and have no
gl_entry_id; cancelling them just marks them Cancelled (no ledger reversal is queued, since the old flow never posted them). Their stored tax is preserved when they are re-saved. business-m-invoicenow depends onbusiness-m-protocols; publish or install both together.- Entries stuck in the outbox as Dead now move their invoice or payment to GL Rejected / Cancel Rejected instead of leaving it Pending GL.
4. Verification & QA Checks
Section titled “4. Verification & QA Checks”To guarantee zero-regression upgrades, complete this three-step verification loop:
Step 1: Run Workspace Unit Tests
Section titled “Step 1: Run Workspace Unit Tests”Verify all sub-library controller and model tests run successfully:
uv run pytestStep 2: Test Frontend Compilation
Section titled “Step 2: Test Frontend Compilation”Confirm that Vite module federation and Tamagui asset compilation passes across all applications:
pnpm -r buildStep 3: Clear Module Federation Caches
Section titled “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/.vitepnpm install