Versioning policy reference
How Notifizz versions and releases the official SDKs — per-package SemVer, deprecation policy, release process per language.TL;DR
- SemVer per package. Each SDK package has its own version line.
- Major bumps for breaking changes, e.g. the SDK shape rework that collapsed everything into a flat
track(), or the removal of the legacyclient.senddirect-write API. - One major of overlap support — the previous major receives security fixes for at least one major-release cycle.
- Each package ships its own
CHANGELOG.md(Keep-a-Changelog format) with the migration notes per major.
SemVer rules
Each SDK package follows SemVer 2.0. The same word means the same thing in every package:
Each package has its own version line —
@notifizz/nodejs@2.0.0 and @notifizz/react@1.5.0 can ship together with no implied dependency.
Breaking-change policy
Breaking changes are minimised but not avoided when they’re the right call:- Removal of misleading APIs — e.g. the chained
client.track(props).workflow(slug, recipients)shape. It forced the developer to know campaign + recipient upfront, contradicting the event-driven model. Kept around longer, it would have set bad patterns; the major bump was the right move. - Removal of broken APIs — e.g.
client.send(...)and the legacy direct-write route. The route threw on every external call; the SDK methods documented a route that didn’t work. Removal is breaking-on-paper but unbreakable-on-code.
- A
CHANGELOG.mdentry under “Breaking” listing every removed/renamed API. - A migration recipe — usually a one-line replacement, occasionally a paragraph for non-trivial cases.
Deprecation window
When an API is being deprecated rather than outright removed:- The deprecated symbol is marked
@deprecatedin TypeScript /@Deprecatedin Java /@deprecatedin PHPDoc. - A console / log warning fires on first use (debug builds).
- The symbol stays callable for one major release cycle after the deprecation lands.
- The next major removes it.
track vs track().workflow()) skip this window: there is no useful “soft” path. The major bump and the migration guide do the work instead.
Where new releases ship
New versions appear on the public registry within minutes of release. Java has an additional Maven Central sync delay of 10–30 minutes after publish.
The three subscribe widget packages carry their own version lines like every other package.
@notifizz/subscribe is the widget bundle and its public types; the two wrappers are what you install in an application. A version line here says nothing about the feature’s availability — the subscribe widget is in closed beta and enabled per organisation, independently of what is published on npm.
CHANGELOG format
Each package ships aCHANGELOG.md in Keep-a-Changelog format:
FAQ
Where's the `@notifizz/nodejs` changelog?
Where's the `@notifizz/nodejs` changelog?
Mirrored on the npm package page. Every SDK ships its
CHANGELOG.md to its public registry (npm / Maven Central / Packagist).How long is the previous major supported?
How long is the previous major supported?
At least one major-release cycle for security fixes. If you’re on v1 and we ship v2, v1 keeps receiving security patches until v3 ships. Functional fixes are best-effort on the previous major; new features land only on the current major.
Will my v0 break on v1?
Will my v0 break on v1?
Possibly — pre-1.0 versions don’t carry the same SemVer guarantees. Early SDK iterations (v0) shipped the chained
track().workflow(...) shape; v1 introduced the flat track(). Migration is documented in the v1 CHANGELOG.How do I subscribe to release notifications?
How do I subscribe to release notifications?
Each public registry (npm, Maven Central, Packagist) lets you subscribe to package updates from its package page — set up the notification mechanism your registry of choice exposes.
Can I pin to a minor or just a major?
Can I pin to a minor or just a major?
Pin to a major (
^2.0.0) for SemVer-flavoured updates — you’ll receive minor + patch upgrades automatically, no breaking changes. Pin to a minor (~2.1.0) if you want only patch updates. Use exact versions only if you’re investigating a regression.Beta / RC versions?
Beta / RC versions?
Pre-release versions ship under tags like
2.0.0-beta.1 (npm next / Maven snapshot / Packagist dev- branch). They’re announced in the relevant CHANGELOG entry under “Pre-releases”. Production code should never depend on a pre-release.See also
Node.js SDK reference
@notifizz/nodejs API and behaviour.Event Tracking overview
Cross-language feature matrix.
Event Tracking
The HTTP wire format the SDKs share.
Error catalogue
All public error codes.