BillKitDeprecation policy
How long a deprecated part of the API, an SDK or the CLI keeps working, how you hear about it, and what each version number promises.
A deprecation is the only route by which something covered by the compatibility contract can be removed. It is rare, it is announced, and the deprecated thing keeps working for the whole notice period.
The API
A field, parameter, endpoint, event type or error code is deprecated with at least 12 months’ notice before it stops working. During that time it behaves exactly as before. Where it has a replacement, the replacement ships first, so there is always a period in which both work and you can move at your own pace.
A deprecation is announced in two places:
- the API changelog, with the date it was deprecated, the earliest date it can be removed, and what to use instead;
- the OpenAPI document, where the operation, parameter or field is marked
deprecated.
Those two are the notice. BillKit does not email account owners about deprecations and does not mark deprecated calls in API responses, so check the changelog when you plan upgrades.
Security fixes are the one exception, as the compatibility contract explains: an unsafe behaviour can be withdrawn without the 12 months.
SDKs and the CLI
Each SDK and the billkit CLI follows Semantic Versioning independently.
Their version numbers are not aligned with each other or with the API.
| Release | What it can contain |
|---|---|
| Patch 1.4.1 | Bug fixes and security fixes. No new surface. |
| Minor 1.5.0 | New methods, parameters, types, commands and flags, and support for new API fields and event types. Deprecations are announced in a minor release; nothing is removed. |
| Major 2.0.0 | Removals of anything deprecated in a 1.x release, renamed or retyped surface, and dropped runtime versions under the supported versions rule. |
A deprecated SDK method or CLI flag keeps working until the next major release, and is removed
only in one. The deprecation is announced in the package’s CHANGELOG.md under the release that
made it. The SDKs and the CLI do not print deprecation warnings at runtime, so the changelog is
where to look.
When a new major version ships, the previous major version receives security fixes for 12 months. It gets no new features and no fixes for non-security bugs in that time. After the 12 months it receives nothing.
Because the API only grows, an older SDK keeps working against it. It simply does not know about fields and endpoints added after it was released, which it passes through untyped or ignores.
Before 1.0
Releases numbered 0.x were made before this policy existed, and a 0.x minor release could and did contain breaking changes. From 1.0.0, the rules above apply to every package.