Versioning & Deprecation Policy
Relevant source files
The following files were used as context for generating this wiki page:
The Meltano Singer SDK maintains a rigorous versioning and deprecation policy to ensure stability for developers building Singer taps, targets, and mappers. This policy governs how new features are introduced, how breaking changes are managed, and how outdated APIs are phased out. The primary goal is to provide a predictable migration path while allowing the framework to evolve.
Sources: CLAUDE.md:105-107, cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:275-277
Deprecation Mechanism
The SDK utilizes a structured warning system to communicate the lifecycle of code elements. Deprecations are handled through specific warning classes defined in singer_sdk/helpers/_compat.py, which provide varying levels of urgency based on the removal timeline.
Warning Classes
The following table details the internal warning classes used to signal different stages of the deprecation lifecycle:
| Class | Base Class | Usage Scenario |
|---|---|---|
SingerSDKDeprecationWarning | DeprecationWarning | Used when a specific removal version has been committed. |
SingerSDKPendingDeprecationWarning | PendingDeprecationWarning | Used for APIs intended for removal but without a committed timeline. Silenced by default. |
SingerSDKPythonEOLWarning | FutureWarning | Used specifically for Python versions nearing or past End-of-Life. |
Sources: CLAUDE.md:89-95
Implementation Logic
Developers and SDK contributors implement deprecations using the deprecated decorator factory. This utility ensures that messages are standardized and that the required warning category is applied.
The diagram shows the logic flow for choosing the appropriate deprecation warning based on the certainty of the removal timeline.
Sources: CLAUDE.md:96-103
Release & Removal Timeline
The SDK follows a strict timeline for moving from a deprecation warning to actual code removal. This ensures that plugin developers have sufficient time to update their implementations.
- Notice Period: A minimum of 3 months notice is required before removal.
- Release Buffer: A minimum of 3 feature releases must occur between the initial warning and the removal.
- Removal Version: A named removal version must be specified for any
SingerSDKDeprecationWarning.
Sources: CLAUDE.md:105-107
Upgrade Workflow for Plugin Developers
When upgrading the singer-sdk dependency in a project's pyproject.toml, developers are instructed to follow a specific migration protocol to catch potential breaking changes before they occur in production.
Step-by-Step Upgrade Process
- Review the Deprecation Guide: Consult the official SDK deprecation page to identify APIs scheduled for removal in the target version.
- Update Dependency: Modify the
pyproject.tomlfile to point to the new version (e.g.,singer-sdk~=X.Y). - Environment Sync: Run
uv syncto update the local development environment. - Enforce Warning Checks: Run the test suite with warnings escalated to errors.
uv run pytest -W error::DeprecationWarning - Address Warnings: Replace deprecated classes, functions, or properties with their recommended alternatives as indicated in the warning message.
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:275-295, cookiecutter/target-template/{{cookiecutter.target_id}}/AGENTS.md:310-330, cookiecutter/mapper-template/{{cookiecutter.mapper_id}}/AGENTS.md:265-285
Versioning Infrastructure
The project uses a Version Control System (VCS) based versioning strategy, managed by hatch-vcs. This allows for dynamic version generation based on git tags and commit history.
Configuration in pyproject.toml
The SDK defines its versioning behavior and dependencies within the pyproject.toml file:
- Dynamic Versioning: The
versionfield is marked as dynamic, handled by thehatch-vcssource. - Release Tooling:
commitizenis used to automate version bumps and changelog generation. - Python Support: The SDK currently supports Python 3.10 through 3.14.
Sources: pyproject.toml:3-5, pyproject.toml:210-213, pyproject.toml:162-163, CLAUDE.md:131
Conclusion
The Versioning & Deprecation Policy is a foundational component of the Meltano Singer SDK, balancing the need for rapid framework evolution with the stability required by the Singer ecosystem. By utilizing a tiered warning system and mandatory notice periods, the SDK ensures that developers can maintain their taps and targets with minimal unexpected disruption.
Sources: CLAUDE.md:105-107, README.md:46-50