Skip to main content

Release Process & Rolling Distribution

Framework M adopts a Rolling Distribution model, enabled by its Hexagonal (Port/Adapter) Architecture. This ensures that the framework can evolve rapidly without forcing downstream applications into complex, version-locked upgrade migrations.

1. Rolling Distribution Model​

Unlike traditional ERP frameworks that use version-specific long-lived branches (e.g., version-13, version-14), Framework M primarily operates on a single release/next pipeline.

Why no Version Forks?​

  1. Reduced Overhead: Maintaining multiple version forks creates a massive maintenance burden for backporting security fixes and features.
  2. Continuous Upgrades: A rolling model encourages users to stay current, significantly reducing the "Upgrade Tax" paid every few years.

2. Port/Adapter Architecture (Stability Guard)​

The core secret to Framework M's stability is its Port/Adapter structure.

  • The Port (Protocol): Defines the interface (e.g., SecretProtocol, DatabaseProtocol). These change very rarely.
  • The Adapter: Implementation of the port. We can rewrite the internal logic of an adapter (e.g., swapping a regex-based parser for an AST-based one) without changing the Port.
  • The Application: Only interacts with the Port. As long as the Port is stable, the application remains functional regardless of framework internal changes.

3. Migration Comparative Analysis​

Common Pitfalls in Odoo/Frappe​

Historically, Odoo and Frappe users face high friction during upgrades due to:

  • Breaking Schema Changes: Dropping or renaming columns in core DocTypes.
  • Path-Dependent Failures: Moving a module from one folder to another breaks imports in custom apps.
  • Blocking Migrations: Production must be stopped while thousands of rows are backfilled.

The Framework-M Way​

ConcernFramework M Strategyvs Odoo/Frappe
Schema ChangesDeclarative sync identifies additive changes as safe; breaking changes require 2-Phase ZDM.Often forces schema changes immediately, causing downtime.
Renames & RefsUses Shadow Tables or View Layers to maintain legacy API support while renaming internals.Renames often break external integrations and reports.
Module MovementsHexagonal structure ensures that business logic is resolved via the registry, not file paths.Moving a python file breaks imports in custom overrides.
Data Migrations2-Phase ZDM (Schema first, then async backfill).Blocking migrations are the default, leading to long downtime windows.

4. Release Automation​

Framework M uses a high-trust, automated CI/CD workflow to manage multi-package releases from the monorepo.

1. Feature Integration​

  • Developers fork main into feat/ branches and submit Merge Requests to main.
  • Merging a feature into main triggers the create-release-mr job.

2. Staging & Aggregation (release/next)​

  • The create-release-mr job automatically creates (or updates) a release/next branch.
  • It scans all packages in the monorepo, determines version bumps, and prepares CHANGELOG.md updates based on the new commits in main.
  • It creates a single Merge Request from release/next back to main that tracks all pending version increases.
  • Aggregation: If multiple feat branches are merged into main, the release/next branch keeps "piling up" the version bumps and changelog entries.

3. Final Release & Tagging​

  • Once the automated MR is reviewed, a developer merges release/next into main.
  • This merge (with a chore(release): message) triggers the auto-tag-release job.
  • The tagger script scans the local changelogs and creates Git tags for every package that was bumped (format: package-name@vX.Y.Z).

4. Publishing​

  • The creation of these tags triggers the final publish stage.
  • Automatic: Packages are instantly published to the GitLab Registry (PyPI/NPM) and TestPyPI.
  • Manual: Final publishing to the official PyPI and NPM registries requires a manual trigger from the tag pipeline for human validation.

5. Stability Contract​

The framework-m-core package carries a strict stability contract. Any breaking change to a public Protocol requires:

  1. Deprecation Period: A minimum of 3 minor releases where the old Port remains available with a warning.
  2. Migration Tooling: A m migrate --fix-api or similar utility to help users update their code automatically.