SDK Versioning and Release: Semantic Versioning, Changelogs, and Distribution

Semantic Versioning for SDKs

Semantic versioning (semver) communicates the impact of changes through the version number: MAJOR.MINOR.PATCH. For SDKs, the rules are:

• PATCH (0.1.0 -> 0.1.1): Bug fixes, documentation updates, internal refactors that do not change the public API.
• MINOR (0.1.0 -> 0.2.0): New features, new methods, new optional parameters. Existing code continues to work without changes.
• MAJOR (0.2.0 -> 1.0.0): Breaking changes — renamed methods, removed parameters, changed return types, dropped Python version support.

The 0.x.x range has a special meaning: the API is unstable. Breaking changes can happen in minor versions. Once you reach 1.0.0, you commit to backward compatibility within major versions.

Single Source of Truth for Version

Store the version in one place and derive it everywhere else. In Python:

flowchart TD
    START["SDK Versioning and Release: Semantic Versioning, …"] --> A
    A["Semantic Versioning for SDKs"]
    A --> B
    B["Single Source of Truth for Version"]
    B --> C
    C["Changelog Generation"]
    C --> D
    D["Publishing to PyPI"]
    D --> E
    E["Publishing to npm"]
    E --> F
    F["CI/CD Release Pipeline"]
    F --> G
    G["Pre-Release Versions"]
    G --> H
    H["FAQ"]
    H --> DONE["Key Takeaways"]
    style START fill:#4f46e5,stroke:#4338ca,color:#fff
    style DONE fill:#059669,stroke:#047857,color:#fff

# src/myagent/_version.py
__version__ = "0.3.1"

Reference it in pyproject.toml:

[project]
name = "myagent"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "myagent._version.__version__"}

And in the HTTP client user-agent header:

from myagent._version import __version__

headers = {
    "User-Agent": f"myagent-python/{__version__}",
}

In TypeScript, the version lives in package.json and is importable:

import { version } from '../package.json';

const USER_AGENT = `@myagent/sdk ${version}`;

Changelog Generation

A changelog communicates what changed, why, and how to migrate. Use Conventional Commits to enable automatic changelog generation:

feat(agents): add batch creation endpoint
fix(retry): honor Retry-After header for 429 responses
docs: add streaming cookbook example
BREAKING CHANGE: rename AgentClient.run() to AgentClient.runs.create()

Tools like python-semantic-release or semantic-release (Node) parse these commits and generate structured changelogs:

## [0.4.0] - 2026-03-17

### Added
- Batch agent creation via `client.agents.create_batch()`
- Streaming support with `client.runs.create_stream()`

### Fixed
- Retry logic now honors `Retry-After` header for 429 responses
- OAuth token refresh race condition under concurrent requests

### Changed
- Minimum Python version raised to 3.10

### Removed
- Deprecated `client.run()` method (use `client.runs.create()`)

Publishing to PyPI

Configure your Python project for PyPI distribution:

# pyproject.toml
[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myagent"
dynamic = ["version"]
description = "Python SDK for the MyAgent AI platform"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.10"
dependencies = [
    "httpx>=0.25.0",
    "pydantic>=2.0.0",
]
classifiers = [
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Typing :: Typed",
]

[project.urls]
Documentation = "https://docs.myagent.ai/python"
Repository = "https://github.com/myagent/myagent-python"

Build and publish:

python -m build
twine upload dist/*

Publishing to npm

The TypeScript SDK publishes to npm. Ensure your package.json includes the right metadata:

{
  "name": "@myagent/sdk",
  "version": "0.3.1",
  "description": "TypeScript SDK for the MyAgent AI platform",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/myagent/myagent-typescript.git"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "prepublishOnly": "npm run build"
  }
}

The "files": ["dist"] field is critical — it limits the published package to only the built files, keeping the package size small and excluding source code, tests, and configuration.

CI/CD Release Pipeline

Automate the entire release process with GitHub Actions:

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - "v*"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -e ".[dev]"
      - run: pytest tests/ -m "not integration"

  publish-pypi:
    needs: test
    runs-on: ubuntu-latest
    environment: pypi
    permissions:
      id-token: write  # For trusted publishing
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install build
      - run: python -m build
      - uses: pypa/gh-action-pypi-publish@release/v1

  publish-npm:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"
      - run: npm ci && npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

  github-release:
    needs: [publish-pypi, publish-npm]
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

Pre-Release Versions

Use pre-release tags for testing before stable release:

# Python: alpha/beta/rc
# 0.4.0a1 -> 0.4.0b1 -> 0.4.0rc1 -> 0.4.0

# npm: dist tags
npm publish --tag beta
# Users install with: npm install @myagent/sdk@beta

This lets early adopters test new features without affecting the latest install channel.

FAQ

When should I bump to version 1.0.0?

When you have three or more production users relying on the SDK and you are confident in the API surface. Version 1.0.0 is a commitment to backward compatibility, not a quality statement. Staying at 0.x gives you flexibility to make breaking changes without a major version bump, which is valuable during early development.

How do I handle breaking changes without alienating existing users?

Follow a deprecation cycle: announce the change, add deprecation warnings in a minor release, document the migration path, and remove the deprecated code in the next major release. Give users at least one minor version cycle (ideally two to three months) to migrate. Never remove a feature without prior deprecation.

Should I publish source maps for the TypeScript SDK?

Yes, include sourcemap: true in your tsup config. Source maps let users debug issues by stepping through the original TypeScript code instead of transpiled JavaScript. This dramatically speeds up bug reports because users can point to exact lines in your source. The file size overhead is negligible since source maps are only loaded by developer tools.

---

#Versioning #Semver #CICD #PyPI #Npm #SDKDistribution #AgenticAI #LearnAI #AIEngineering