Versioning and deprecation

What a version number promises, how breaking changes are announced, and how deprecated APIs are retired.

Semantic versioning

fate follows SemVer 2.0.0: MAJOR.MINOR.PATCH.

Bump	Means
MAJOR	Incompatible API changes.
MINOR	Backward-compatible features.
PATCH	Backward-compatible fixes.

Releases and the changelog are generated by release-please from the commit history, so every released change appears there.

While the engine is v0.x

Minor versions may contain breaking API changes until v1.0.0. This is ordinary SemVer behaviour for 0.x, and it lets the API settle before a major release freezes it.

Every breaking change is listed under a Breaking heading in the changelog. Read it before bumping a minor version, and pin a known-good version in your go.mod in the meantime:

go get github.com/arisros/[email protected]

The Temporal module versions separately

The Temporal integration (github.com/arisros/fate/temporal) is a separate Go module with its own tags, so it can release on its own cadence and its version need not match the engine's. Upgrade the two independently:

go get github.com/arisros/fate@latest
go get github.com/arisros/fate/temporal@latest

How deprecations work

An API that is going away is retired in three steps, so it is never removed without warning.

1. Announce. The symbol gets a Go // Deprecated: doc comment naming its replacement. gopls and staticcheck then flag every use, in the editor and in CI. It is also listed under Deprecated in the changelog.
2. Coexist. The deprecated symbol keeps working alongside its replacement for at least one minor release, so you can migrate gradually.
3. Remove. It is removed in a later release and listed under Breaking in the changelog, together with the migration step.

// Deprecated: use ResolveInvocation instead. Removed in a future release.
func (a *Actor) Resolve(id string, out any) error

Upgrading safely

• Read the changelog from your current version forward, checking every Breaking and Deprecated heading.
• On v0.x, bump one minor at a time rather than skipping across several breaking minors.
• Run go vet ./... and staticcheck ./...; deprecation warnings surface there.
• Lean on your tests. Because the engine is deterministic, a suite that passes before and after an upgrade is strong evidence of behavioural parity.

Reporting a regression

If you hit a regression or an undocumented breaking change, please open an issue at github.com/arisros/fate/issues.