Release Policy

This page describes the release policy for the Formance Platform and its components. This policy is subject to change; the latest version is the one available on this website.

The Formance Platform is released as a Stack: a coherent, reproducible, and supported set of components.

Stack releases#

A Stack release is a versioned compatibility line backed by an exact manifest of component versions.

The Stack version exposed at runtime identifies the compatibility line, for example v3.2. The exact composition of the Stack is pinned in the Helm Chart and versioned through chart revisions. A deployment never resolves component versions dynamically: the installed component versions are the versions pinned by the applied chart.

The Stack version keeps three segments, but it does not follow strict SemVer:

For example, v3.2.x represents the v3.2 compatibility line. A new chart revision for that line can update one or more compatible components while the runtime Stack line remains v3.2.

Compatibility contract#

All components embedded in the same Stack line must be compatible with:

• the Ledger version embedded by that line;
• the other embedded components;
• the public APIs exposed by the Stack line;
• the migrations and schemas supported by the Stack line;
• the operational constraints of the target deployment.

A component version can only be integrated into an existing Stack line if it respects that contract. If it requires an incompatible API change, migration, Ledger dependency, or operational requirement, it must be released through a new Stack compatibility line or documented as an explicit exception.

Component release regimes#

Components keep their own SemVer versioning. Within a component major version, releases are expected to remain compatible with that component's public contract.

The Stack does not mechanically propagate component minor or patch versions into the Stack version. For components other than Ledger, compatible minor and patch bumps can be integrated into an existing Stack line as Stack patch revisions. A new Stack compatibility line is required when one of those components moves to a new major version, or otherwise introduces a change that breaks the Stack compatibility contract.

Whether that new Stack line is a Stack minor or a Stack major depends on the impact on the Stack contract: a Stack minor introduces a new compatibility line, while a Stack major breaks compatibility for existing users.

Ledger#

Ledger is pinned for each supported Stack line.

Ledger holds client data and carries high-impact migrations, so each Stack line pins an exact Ledger version. Fixes can be backported to the supported Ledger line, then integrated by publishing a new compatible chart revision. An incompatible Ledger migration requires a new Stack compatibility line.

Rolling within major components#

The following components are released as rolling within major components:

• transaction-plane
• payments
• wallets
• flows
• reconciliation
• webhooks
• auth
• gateway

These components keep their own SemVer, but compatible features and fixes can be integrated into an existing Stack line as long as they remain compatible with the component major version and the Stack compatibility contract.

A compatible bump of one of these components produces a Stack patch revision. This means a Stack patch can include a new feature from a rolling component, provided the feature does not break the Stack line.

Helm Chart and Versions CRD#

The Helm Chart is the technical source of truth for the exact composition of a Stack release. For a published chart revision, the manifest is immutable. Any component version change requires a new chart revision and a change visible in Git.

The Versions CRD (versions.formance.com) exposes the installed Stack compatibility line and the component versions embedded by the applied chart. It must make support and diagnostics able to map a Stack line to concrete component versions, for example:

stack: v3.2
modules:
  ledger: 2.3.4
  transaction-plane: 1.4.2
  payments: 1.12.3
  wallets: 1.7.0
  flows: 1.9.1
  reconciliation: 1.3.5
  webhooks: 1.5.0
  auth: 1.8.2
  gateway: 1.6.4

Changelog#

The Stack changelog is part of the release contract. Each Stack release must list the component deltas since the previous chart revision in the same line, including:

• features;
• fixes;
• security fixes;
• migrations;
• configuration changes;
• known risks or required operator actions.

A release is not considered complete if this information is not available.

Security and support#

Security fixes are integrated by publishing new chart revisions for the relevant supported Stack lines. When a fix is compatible with an existing line, the Stack compatibility line remains the same and only the chart revision changes.

The Formance Platform supports the last two Stack compatibility lines, commonly referred to as N and N-1. These lines continue to receive compatible fixes, especially security fixes.

If a security fix cannot be applied compatibly to a supported line, Formance may provide a compatible backport, require an upgrade to a more recent Stack line, or document a support exception.