> ## Documentation Index
> Fetch the complete documentation index at: https://notifizz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifizz SDK Versioning Policy

> How Notifizz versions its SDK packages — SemVer per package, breaking-change policy, deprecation window, release process.

# 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](https://semver.org). The same word means the same thing in every package:

| Bump                | Meaning                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| **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

| SDK                                 | Registry      | Install                                                   |
| ----------------------------------- | ------------- | --------------------------------------------------------- |
| `@notifizz/nodejs`                  | npm           | `npm install @notifizz/nodejs`                            |
| `com.notifizz:notifizz-java`        | Maven Central | Maven / Gradle dependency on `com.notifizz:notifizz-java` |
| `notifizz/php`                      | Packagist     | `composer require notifizz/php`                           |
| `@notifizz/{react,angular,vanilla}` | npm           | `npm 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](https://keepachangelog.com/) format:

```markdown theme={null}
## [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

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Node.js SDK reference" icon="node-js" href="/docs/sdks/event-tracking/node-js">
    `@notifizz/nodejs` API and behaviour.
  </Card>

  <Card title="Event Tracking overview" icon="satellite-dish" href="/docs/sdks/event-tracking/overview">
    Cross-language feature matrix.
  </Card>

  <Card title="Event Tracking" icon="code" href="/docs/sdks/event-tracking/overview">
    The HTTP wire format the SDKs share.
  </Card>

  <Card title="Error catalogue" icon="circle-exclamation" href="/docs/sdks/error-catalogue">
    All public error codes.
  </Card>
</CardGroup>