How to maintain an SDK: releases, runtimes and support

How do you maintain an SDK?

Treat the SDK as a product with an owner, supported runtime matrix and published compatibility policy. Connect its releases to API changes, run tests even when no one edits the repository, keep dependencies current and explain deprecations before removing anything. Track which package versions reach your API so support decisions are based on actual usage.

Maintenance works best as a routine: small predictable updates are easier for users than occasional years of accumulated breaking changes.

Release with every API change

An API update should trigger a review of every supported client. For generated libraries, rebuild from the changed spec and inspect the diff. For handwritten ones, check the operations and types explicitly. The package can follow the API immediately or on a well-publicized release schedule, but its documentation must say which API behavior it targets.

There is a concrete account from Stripe's API Services team. In Stripe's 2024 announcement of a new API release process, Michael Glukhovsky and Wissam Abirached explained that developer feedback had made an unpredictable update stream difficult to plan around. Stripe adopted a more predictable cadence, with larger scheduled updates and smaller feature releases. Crucially, the team said each API release would include corresponding SDK releases and documentation. The package became part of the release contract, rather than something to catch up when convenient.

Test on every supported runtime version

An SDK is installed into other people's environments. Python, Node, Java and Go runtimes move independently of your API; a dependency update can also break an old runtime without anyone touching the SDK's source. Run a matrix covering the oldest and newest supported versions on every pull request, plus a scheduled run to catch upstream changes.

# Example Python portion of a GitHub Actions matrix
strategy:
  fail-fast: false
  matrix:
    python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']

Only include versions you have actually committed to support, and follow upstream support lifecycles rather than keeping the matrix static forever.

Keep dependencies current

SDK dependencies are inherited by every application that installs the client. Reduce unnecessary ones, allow compatible ranges when sensible and review automated updates in CI. Security changes may need a patch release even when the API itself is unchanged. A changelog entry should identify whether callers need to do anything besides upgrade the package.

Publish a support policy

Document which package major versions receive bug and security fixes, which runtimes are supported, how deprecations are announced and where security issues should be reported. An unmaintained major remaining available on a registry is not necessarily supported. Say so plainly and link to migration instructions for the next version.

Stripe's coordination of API and SDK releases illustrates why a version map matters: the application may be pinned to a client package long after the service adds new capabilities.

Retire old runtimes on a schedule

Choose a support window, warn about upcoming runtime removals and test that the new release still installs on every runtime you claim to support. Removing Python 3.x or an old Node LTS line may be reasonable, but it becomes a breaking operational surprise when it appears without advance notice.

Deprecate before you remove

Mark a method deprecated in doc comments and reference pages, name its replacement and provide a migration sample. Remove it only in a deliberately breaking release. A compatibility alias can give adopters time to move without preventing the library from evolving.

Keep a changelog and triage issues

Each release note should cover new API operations, changed method shapes, error behavior, runtime changes and dependency fixes. Triage issues on a schedule, separate SDK bugs from service bugs, and link fixes to the package versions that contain them. Good triage prevents the same integration problem from being rediscovered by every new customer.

Know which versions are in use

Set a distinctive, privacy-conscious user agent such as acme-python/2.4.0. Aggregate it by active organization and feature use, not only raw request counts. A single high-volume customer should not conceal hundreds of smaller integrations that still depend on an old major.

The information helps you decide how long to support old clients and whether a planned API change will disrupt real users.

SDK maintenance checklist

Verify that every API release has a client impact review, supported runtimes have passing tests, package artifacts install cleanly and docs examples target a released version. Check dependency alerts and the issue queue weekly. Before dropping a major, publish a migration path and look at version adoption.

Maintaining SDKs with Octri

Generation from a shared API description can make regular SDK releases less laborious, while Octri's language-specific settings help preserve interface choices across rebuilds. Still appoint maintainers for release review, compatibility and security; automation does not own the support promise.