Developer docs

Versioning and compatibility

What a BookDinePlay version number means, which changes can arrive unannounced, what we promise for API, SDKs, plugin and MCP, and how deprecation works.

You build on BookDinePlay so that it keeps working while we keep improving it. This page says exactly what we promise, what can change without warning, and how you hear about what will break. Every promise here is either enforced by a test in our build or by the release process; where it is not, we say so.

What a version number means

BookDinePlay is released as one numbered set, tagged vX.Y.Z on GitHub. The same number names everything that ships to you:

Artifact Where the version shows
JavaScript SDK The CDN path cdn.bookdineplay.com/sdk/<version>/bookdineplay.js
.NET packages BookDinePlay.Sdk and BookDinePlay.Shared on nuget.org
WordPress plugin bookdineplay-<version>.zip on the GitHub release
API and MCP server Deployed with the release; the API has no version in its URL

A version with a - in it (for example 0.24.0-rc.1) is a pre-release. A pre-release is published only under its exact version path: it never moves the CDN's major-line alias, and it is not listed in the changelog.

Read the number as major.minor.patch. A patch fixes behaviour without changing what you can call. A minor adds capability and can append to contracts, as explained below. A major is the only release that may break something you built against what this documentation describes.

What the promise covers

The promise covers what this documentation describes: the routes under API reference, the problem types in Errors, the options and methods of the JavaScript SDK, the .NET SDK with its contracts, the shortcodes and attributes of the WordPress plugin, and the tools and prompts of the MCP server. Anything not described here — an internal route, the console's own interface, a field you found in a response that no page names — can change in any release.

Changes that can reach you in any release

These are not breaking, and your integration must tolerate them:

  • New routes, new optional request fields and new response fields. Ignore fields you do not know.
  • New values where a field is a set of named values: a reservation or ticket status, a resource type, the reason of a refusal, a problem type, a plan's feature. Handle an unknown value gracefully rather than failing.
  • New optional parameters on SDK methods, new SDK methods, new widget options, new shortcode attributes, new MCP tools and prompts.
  • Stricter protection of the platform: a rate limit is the standing example. It will be announced in advance, never switched on silently, and signalled the standard way (429 with Retry-After) — see Rate limits.

One consequence needs a plain warning. The .NET SDK reads named values strictly: a status it does not know makes deserialisation throw a JsonException, rather than hand you a surprise string. The release that introduced the PaidButUnavailable reservation status is the example, and it is why the changelog always says when a release adds such a value and which SDK version you need. Keep the SDK reasonably current; the JavaScript SDK passes unknown values through.

What counts as breaking

A change is breaking when something that worked as documented stops working. In particular: removing or renaming a route, a field, an SDK method, an option or a tool; changing the type of a field; changing the meaning of a status or the status code of a refusal; making an optional request field required; narrowing what a limit documented in the reference allows. Breaking changes are marked Breaking in the changelog, are rare, and from version 1.0 happen only in a new major version, after the deprecation period below.

The published contracts

BookDinePlay.Shared — the request and response types the SDK and the API share — ships on nuget.org, so a change to one is a change to a public interface with consumers outside this repository. What we promise:

BookDinePlay.Shared promises source compatibility and JSON compatibility. Recompilation is required across a minor bump. Dropping a newer assembly in next to a consumer compiled against the older one, without recompiling, is explicitly not supported.

How that works, so you can plan around it. Contracts are positional records, and they grow by appending trailing optional parameters. Appending replaces the record's constructor and Deconstruct with longer ones: your source still compiles, because the new parameters are optional, and an old payload still deserialises, because absent members take their default. Only an assembly that was already compiled notices, as a MissingMethodException at run time — which is why you recompile when you update the package.

Within that, we never insert a parameter in the middle, never rename a member, never change a member's type, and never make an existing member required. A constant such as a maximum length is compiled into your assembly, so narrowing one changes nothing for you until you rebuild.

This is not left to goodwill: a test writes the whole public surface of BookDinePlay.Shared to an approved snapshot and fails the build on any change, saying whether it is an append or an incompatibility. Approving that snapshot is the public-API review. The test also replays the payload every earlier shape of each record would have sent, to prove the members that were there still come back unchanged. What it does not check is binary compatibility, because that is not promised.

The JavaScript SDK and the CDN

The CDN serves the SDK under two path shapes with different guarantees:

Path Content Cache
sdk/<version>/bookdineplay.js One exact release. Immutable: its bytes never change One year
sdk/v<major>/bookdineplay.js The latest release of that major line Five minutes

Use the alias when you want fixes without touching your page. A new major version gets its own alias (sdk/v1/ after sdk/v0/), and the old alias keeps serving the last release of its line: an alias never jumps to a new major version, so your page changes major version only when you change the path. Pin an exact version with its integrity hash when your policy demands byte-for-byte reproducibility. The hash is published next to the file as sdk/<version>/sri.txt and on the GitHub release, only ever for an exact version — never for the alias, whose content changes by design. See CDN for the details.

Deprecation

When something will be removed, you hear about it first and have time to move:

  1. Announced. The release that deprecates it lists it in the changelog under Deprecated, naming the replacement, and the reference page for the item says so. In the .NET SDK the member is marked [Obsolete] with the replacement in its message.
  2. Still working. A deprecated item keeps working, unchanged, for at least six months after the release that announced it, and it is never removed in a release that is not a new major version.
  3. Removed. The removal is listed under Breaking in the changelog of the major release that does it.

The only exception is a security or legal reason that does not allow waiting. In that case the change is announced the same day, with the reason, and the changelog says that the period was shortened.

How you find out

  • The changelog lists every stable release, newest first, with everything an integration can notice. A stable release is not published without its entry: the release process refuses a stable tag that has no section for its version in both languages.
  • Each GitHub release links the packages and the SDK's integrity hash.
  • The Compatibility section of the BookDinePlay.Shared package readme repeats the contract promise above where a package consumer will see it.

Next steps

  • Changelog — what changed, release by release.
  • CDN — pinning an exact SDK version.
  • .NET SDK — the typed client and its contracts.