---
title: "SDK Versioning and Release: Semantic Versioning, Changelogs, and Distribution"
description: "Learn how to implement semantic versioning, generate changelogs automatically, publish to PyPI and npm, and set up CI/CD release pipelines for AI agent SDK distribution."
canonical: https://callsphere.ai/blog/sdk-versioning-release-semver-changelogs-distribution
category: "Learn Agentic AI"
tags: ["Versioning", "Semver", "CI/CD", "PyPI", "npm", "SDK Distribution", "Agentic AI"]
author: "CallSphere Team"
published: 2026-03-17T00:00:00.000Z
updated: 2026-05-06T01:02:43.133Z
---

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

> Learn how to implement semantic versioning, generate changelogs automatically, publish to PyPI and npm, and set up CI/CD release pipelines for AI agent SDK 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:

```mermaid
flowchart LR
    DEV(["Developer push"])
    PR["Pull request"]
    LINT["Lint plus type check"]
    TEST["Unit and integration"]
    EVAL["LLM eval gate"]
    BUILD["Build container"]
    SCAN["SBOM plus CVE scan"]
    REG[("Registry")]
    STAGE[("Staging deploy
auto")]
    SOAK["Soak test plus
canary metrics"]
    PROD[("Production deploy
manual gate")]
    DEV --> PR --> LINT --> TEST --> EVAL --> BUILD --> SCAN --> REG --> STAGE --> SOAK --> PROD
    style EVAL fill:#4f46e5,stroke:#4338ca,color:#fff
    style SOAK fill:#f59e0b,stroke:#d97706,color:#1f2937
    style PROD fill:#059669,stroke:#047857,color:#fff
```

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

Reference it in `pyproject.toml`:

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

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

And in the HTTP client user-agent header:

```python
from myagent._version import __version__

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

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

```typescript
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:

```markdown
## [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:

```toml
# 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:

```bash
python -m build
twine upload dist/*
```

## Publishing to npm

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

```json
{
  "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:

```yaml
# .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:

```bash
# 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

---

Source: https://callsphere.ai/blog/sdk-versioning-release-semver-changelogs-distribution