Compatibility

From 1.0.0 on, releases follow Semantic Versioning. This page defines the public surface that version numbers protect: what you, your scripts, your client configuration and the models that use the server can rely on within a major version, and what may change in any release.

What 1.0 freezes#

A change that breaks anything in this list needs a new major version, unless it goes through the deprecation policy first.

What it does not freeze#

These may change in any release, including patch releases:

• Text written for people or models: tool and prompt descriptions and titles, argument descriptions, the summary text of results, error messages, warnings, notes, the server instructions, the rendered text of prompts and the wording of confirmation previews. Models read them, so they improve over time; do not parse them.
• Logs: the server's stderr lines, the JSON request log of remote mode, its field names and its event names.
• OAuth endpoints: clients discover /authorize, /token and /revoke from the metadata documents, so their paths may move. The metadata documents (/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource) are not frozen separately: their paths and format are those of RFC 8414 and RFC 9728, which clients rely on.
• Tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) may change, but only toward more caution, for example a tool newly marked as destructive.
• HTML pages: the consent page, the approval pages, the sign-in, upload and download pages, their layout, text and form fields.
• The setup-problem mode: with an invalid configuration the stdio server starts with only sevdesk_setup_problem (Configuration); that tool's name and output may change.
• Which tools a configuration offers beyond the rules above: new tools can appear in a toolset in a minor release, and tools that need a folder or remote file transfer appear only when it is configured.
• Limits and tuning: page sizes, size caps, timeouts and the pacing of requests, as long as existing arguments stay valid.
• Internals: the package exports no library API; its modules, the build output, test fixtures, scripts and the evals can change at any time.

Breaking and non-breaking changes#

Breaking (a major version, or a deprecation first):

• removing or renaming anything in the frozen list;
• changing the type or the meaning of an argument, output field, value or variable;
• making an optional argument required, or refusing values that were accepted;
• moving a tool to another toolset or a higher tier;
• changing a default so that the server allows more than before (more tiers, more toolsets, weaker confirmation).

Not breaking (a minor release):

• new tools, prompts, toolsets, resources, variables and commands;
• new optional arguments, new accepted input values, new output fields;
• new events or fields in the audit log;
• a new value in an output enum when sevDesk itself introduces it (for example a new document status). Clients should treat a value they do not know as "other".

Exceptions. A fix for a security vulnerability may break compatibility in a minor or patch release when there is no safe alternative; the advisory and the release notes say so. When sevDesk changes or removes an endpoint, a tool may have to change with it; the release notes say what changed and why.

Deprecation policy#

A name that is going away is deprecated first:

1. The old name keeps working next to the new one, at least until the next major release and for at least three months.
2. The deprecation is announced in the release notes and the changelog. A deprecated tool or argument says so at the start of its description (Deprecated: use … instead.), so models prefer the new one; the tool reference shows it. A deprecated environment variable triggers a warning in the server log at startup.
3. The next major release removes it, listed under breaking changes in its release notes.

Pull requests that change the public surface follow the same rules (CONTRIBUTING.md).

Changes from 0.x#

Before 1.0, a review renamed these so the frozen names are consistent. Configurations and scripts written for 0.x need the new names.