Compatibility

Datanotes follows semantic versioning. The version number tells you what an update can change.

Versions

• Major (4.0.0): can change or remove parts of the public interface. The release notes list those changes first, with what to do.
• Minor (3.1.0): adds to the public interface without breaking what works.
• Patch (3.0.1): fixes bugs and changes nothing you rely on.

The release notes describe every version.

The public interface

These parts of Datanotes follow the version rules:

• Operations, their arguments and their answer fields
• HTTP routes and headers
• Violation codes
• Commands, their options and their exit codes
• Environment variables and settings
• The words of metastore.yaml

These cases fall outside them:

• Security fixes: a fix can change a behavior. The release notes say so.
• Bugs: Datanotes fixes behavior that contradicts the documentation.
• Undocumented behavior: only what the docs describe is covered.
• Messages: the text of refusals and hints can improve in any version.
• Node.js versions: support follows the Node.js long-term support releases.

Write tolerant clients

Answers can gain fields, and enums can gain values. Write your client to accept them:

• Ignore fields you don’t know.
• Handle an enum value you don’t know, for example as “other”.
• Read refusals by their HTTP status, not by their text.

import { DatanotesClient } from "datanotes/client";

const db = new DatanotesClient({
  url: "http://127.0.0.1:27150",
  token: process.env.DATANOTES_TOKEN ?? "",
});

type Created = { planned_creates: string[] };

const r = await db.call("insert_row", {
  table: "film",
  values: { title: "Metropolis" },
});
// read the fields you need: new ones may appear
if (r.ok) console.log((r.value as Created).planned_creates);

How the tests check it

The repository keeps the public interface in contract/datanotes-3.txt. It has one line for every operation, argument, answer field, route, command option, environment variable, setting and violation code.

The test suite fails when a line goes or changes within a major version, so a breaking change cannot ship by accident. A second test checks every new name against the naming rules.