Versioning & deprecation

This page is the contract: what a version number promises, how breaking changes are announced, and how deprecations are retired. It is intentionally short so it stays true.

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.

The v0.x caveat

We are pre-1.0

While the engine is in v0.x, minor versions may contain breaking API changes. This is normal SemVer for 0.x and lets the API settle before v1.0.0 freezes it.

Every breaking change is called out under a Breaking heading in the changelog. Read it before bumping a minor version.

Pin a known-good version in your go.mod while on v0.x:

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 (e.g. temporal/v0.4.1). It can release on its own cadence; 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

When an API is going away, it is retired predictably — never yanked without warning:

1. Announce. The symbol is marked with a Go // Deprecated: doc comment naming the replacement. gopls and staticcheck then flag every use in your editor and CI. It also appears 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 without a flag day.
3. Remove. It is removed in a later release, listed under Breaking in the changelog with the migration step.

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

How to upgrade safely

1. Read the changelog from your current version forward — check every Breaking and Deprecated heading.
2. Bump one minor at a time on v0.x; don't skip across multiple breaking minors.
3. Run go vet ./... and staticcheck ./... — deprecation warnings surface here.
4. Your tests are the safety net: because the engine is deterministic, a passing suite before and after an upgrade is strong evidence of behavioural parity.

Reporting

Found a regression or an undocumented breaking change? Open an issue: github.com/arisros/fate/issues.