Skip to main content

​
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 legacy client.send direct-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:
BumpMeaning
Major (x.0.0)Breaking change — caller must update code or configuration. Documented in CHANGELOG.md under “Breaking”.
Minor (0.x.0)Backwards-compatible feature addition. Existing code keeps compiling and behaving.
Patch (0.0.x)Backwards-compatible bug fix or internal-only change (deps, build, types).
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.
Each major release ships:
  1. A CHANGELOG.md entry under “Breaking” listing every removed/renamed API.
  2. 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 @deprecated in TypeScript / @Deprecated in Java / @deprecated in 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.
Cleanly removed APIs (where the new shape is incompatible — 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

SDKRegistryInstall
@notifizz/nodejsnpmnpm install @notifizz/nodejs
com.notifizz:notifizz-javaMaven CentralMaven / Gradle dependency on com.notifizz:notifizz-java
notifizz/phpPackagistcomposer require notifizz/php
@notifizz/{react,angular,vanilla}npmnpm install @notifizz/<framework>
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.

​
CHANGELOG format

Each package ships a CHANGELOG.md in Keep-a-Changelog format: 
## [2.0.0] - 2026-04-27 (Breaking)

### Breaking
- Removed `client.send(...)`. Migrate to `client.track(eventName, properties)`.

### Added
- Enricher subsystem: `client.enricher()`, `client.dispatch(body)` (Node only — body-only webhook entry point).

### Changed
- `webhookSigningSecret` is now an optional 3rd constructor argument, required only when calling `dispatch()`.

​
FAQ

Mirrored on the npm package page. Every SDK ships its CHANGELOG.md to its public registry (npm / Maven Central / Packagist).
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.
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.
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.
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.
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.