Skip to content

Release notes

What changes for the people who run a Factoryal install and the code that talks to it. Newest first.

Contract support window

Since contract 1.0, a client built against any Factoryal release from the last 6 months, or the last 2 minor releases, whichever is longer, keeps working against the current one:

  • HTTP API. /v1 only grows. A removed or changed route, field or parameter needs /v2, and the old one is deprecated first: deprecated: true in the OpenAPI file, Deprecation and Sunset headers on its responses, and an entry under Deprecated below. It's removed only after its Sunset date.
  • Events. Each event type's major (.v0 today) stays readable by old and new consumers. A breaking change to an event is a new major, published alongside the old one until the old one's sunset date.

The rules are in contracts/README.md and ADR-0003.

1.0.0 (unreleased)

Contract 1.0

  • The HTTP API (/v1) and the event types are declared contract 1.0: the OpenAPI file contracts/openapi/factoryal.v1.json and the AsyncAPI file contracts/asyncapi/factoryal.v1.yaml are at version 1.0.0. The support window above starts with this release.
  • The existing event types keep their .v0 names, deliberately. They are stable from this release; they are not renamed to .v1, although no install exists yet to keep them for: the name is part of every event's type, and renaming them would only add churn for no consumer's benefit. The next breaking change to an event is .v1, published alongside .v0.
  • GET /v1/registry/report, the pre-release name of GET /v1/config/report, is gone (404). It was never part of the OpenAPI file.
  • Errors are RFC 9457 Problem Details with a stable code (Errors).
  • Every event is a CloudEvent 1.0 with a published data schema.

Deprecated

Nothing yet.