Release & compatibility

Purpose

Define how leekimerp evolves alongside Frappe / ERPNext and integrators who call whitelisted APIs. This page centralizes policy; detailed commands remain on Deployment & operations and Operational runbook. API naming and inventory live in Whitelisted API inventory.

Versioning model

Artifact	Practice
Git	main is the integration branch; release tags (vX.Y.Z) are recommended for customer handover and audit — adopt per your org.
Python package	Version in setup.py / pyproject.toml (if present) should match tagged releases when you publish tags.
Frappe / ERPNext	Not fully pinned inside this app; record bench version for staging and production in an internal wiki (Deployment & operations — version pinning).

Semantic intent (app-level)

Use semantic meaning even if release mechanics vary:

Change type	Meaning	Integrator / operator expectation
Patch (Z)	Bug fixes, safe migrations, doc-only	Drop-in deploy after bench migrate; no client code change.
Minor (Y)	Additive APIs, new optional fields, backward-compatible behavior	Clients opt in to new features; defaults preserve old behavior.
Major (X)	Removed or renamed whitelisted methods, incompatible DocType schema for external consumers, intentional workflow change	Deprecation window (see below), release notes, ADR if architectural.

Breaking changes

Breaking includes, non-exhaustively:

• Removing or renaming a @frappe.whitelist method.
• Changing required parameters or response shape for a documented integration contract.
• Dropping or repurposing fields that external reports or scripts rely on (document exceptions).

Process:

1. Announce in release notes / internal comms with a deprecation period (org-defined; many teams use one or two release cycles for internal APIs).
2. Record an Architecture decision if the change reflects a new integration or security posture.
3. Update Whitelisted API inventory in the same PR as the code change when possible.
4. Re-run regression tests per Test strategy and attach evidence per Test evidence & CI.

Prefer additive parameters with defaults over renames (API inventory — contract policy).

Frappe / ERPNext upgrades

1. Read upstream Frappe / ERPNext / HRMS release notes before bumping.
2. Pay special attention to DocType overrides (Overrides overview) — core field renames break overrides silently until runtime.
3. Run the regression set listed on Deployment & operations (Sales Invoice, payroll, Xero, Stripe webhooks, Lee Kim flows).
4. Update handover docs when extension points or schema documented on this site change (Operational runbook — Handover docs sync).

Documentation and migrations

Change	Documentation duty
New whitelisted method	API inventory + security review if allow_guest
Scheduler / doc_events	Schedulers, Doc events
DocType JSON affecting generated pages	npm run generate:doctypes + CI green (Test evidence)

Related

• Engineering deliverables hub
• NFR & SLO — availability targets during cutovers
• Test strategy