Versioning and deprecation

A version names a contract that exists, not one that is planned.

ESFI format versions identify an implemented contract. A version describes what a conforming implementation actually emits or accepts; it is not a roadmap label.

Version numbers

Published specifications use a minor version such as 0.7. The document and generated output declare that minor version.

A new minor version is required when the format contract changes: fields are added or removed, required behaviour changes, serialisation or identity rules change, or an existing consumer can no longer rely on the previous specification. A breaking change is any change that can make previously conforming producers or consumers incompatible, including changing the meaning of an existing field or making an optional field required.

Patch fixes do not change the version declared by a document. Corrections that leave the format contract unchanged are recorded as changelog entries against the published minor version. Examples include correcting prose, clarifying an already-implemented rule, or fixing an implementation defect so that output again matches the published contract.

If a change alters the contract rather than restoring or clarifying it, it is not a patch fix; it requires a new minor version.

Specification, implementation and practice

The MPF documentation marks every rule with one of three statuses: Specification 0.7, Reference implementation or ESFI practice. See the Overview.

The markers also describe how a rule can change status:

A reference implementation behaviour that the specification text does not describe becomes normative only when a published specification version describes it. Until then, implementers may rely on it in practice but not as part of the contract.
An ESFI practice, such as a discovery convention used on ESFI sites, becomes part of the contract only through a new specification version. Documenting it does not make it normative.
A rule is never promoted to the specification by a patch fix. Promotion changes the contract, and a changed contract requires a new minor version.

This keeps the published specification narrow and reliable: it states what conforming producers and consumers can depend on, and nothing that is merely convenient or customary.

Published versions are permanent

Once an ESFI format version is published, its specification page remains published and reachable. A newer version does not replace the historical page in place.

This gives implementers a stable reference for documents that continue to declare an older version, and makes historical machine-readable output interpretable without reconstructing an earlier specification.

Deprecation and retirement

A version may be deprecated when ESFI recommends migration to a newer version. Deprecation changes the recommendation, not the historical specification: the deprecated version remains reachable and its documented contract is not rewritten to match the successor.

A version is retired when ESFI no longer treats it as a current implementation target. Retirement is recorded on that version’s page together with the successor, when one exists. Retirement does not remove the page.

Consumers should read the version declared by the document they are processing. Producers should emit the version whose published contract they implement.

Current and previous MPF versions

MPF documents currently declare mpf: '0.7'. The implemented behaviour is documented in the Specification 0.7.

MPF 0.6 is the previous published version. Its Specification 0.6 remains available for documents that still declare mpf: '0.6'.

Positions are versioned differently

The topic pages on this site are positions, not format contracts. They do not carry version numbers. When a position changes materially, the change is recorded at the foot of the topic page with its date. See How to read our claims.