Releasing & Versioning

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• CHANGELOG.md
• pyproject.toml
• dbt_common/semver.py

Releasing and versioning in dbt-common involves a structured process of managing semantic versions, documenting changes via automated changelog tools, and distributing the package to PyPI. As a shared utility used by dbt-core and various adapter implementations, the project adheres to strict Semantic Versioning (SemVer) principles to ensure compatibility across the dbt ecosystem.

Sources: README.md:3-5, CONTRIBUTING.md:1-5, pyproject.toml:1-10

Release Workflow

The release process is driven by GitHub Actions and automated tooling to ensure consistency. Releases are published to PyPI and require coordination with downstream packages like dbt-core and dbt-adapters.

Automated Release Steps

The primary mechanism for releasing a new version is the release.yml workflow. This workflow automates:

1. Version bumping based on the current state of the repository.
2. Generation of the CHANGELOG.md.
3. Publishing the distribution packages to PyPI.

Sources: README.md:7-9, pyproject.toml:117-123

Downstream Updates

When a new major version or pre-release is published, maintainers must manually bump the dbt-common dependency in several related repositories.

Repository	File Path
dbt-core	core/setup.py
dbt-adapters	pyproject.toml
dbt-postgres	pyproject.toml
dbt-snowflake	setup.py
dbt-bigquery	setup.py

Sources: README.md:10-17

Semantic Versioning Logic

The dbt_common/semver.py module implements the logic for parsing, comparing, and reducing version ranges. This is critical for determining dependency compatibility within the dbt ecosystem.

Version Components

The project uses standard SemVer components including Major, Minor, Patch, Prerelease, and Build metadata. The parsing logic is defined via a complex regular expression that enforces strict formatting (e.g., no leading zeros in numeric components).

@dataclass
class VersionSpecification(dbtClassMixin):
    major: Optional[str] = None
    minor: Optional[str] = None
    patch: Optional[str] = None
    prerelease: Optional[str] = None
    build: Optional[str] = None
    matcher: Matchers = Matchers.EXACT

Sources: dbt_common/semver.py:22-29, dbt_common/semver.py:53-64

Version Comparison and Matching

Versions are compared using a natural comparison algorithm (_nat_cmp). This ensures that 1.10.0 is correctly identified as greater than 1.9.0. The system supports several matchers:

• Exact (=)
• Greater Than (>) / Greater Than or Equal (>=)
• Less Than (<) / Less Than or Equal (<=)

The diagram shows how a raw version string is parsed into a specifier and evaluated against ranges to determine compatibility.
Sources: dbt_common/semver.py:10-18, dbt_common/semver.py:126-140, dbt_common/semver.py:284-290

Changelog Management

dbt-common uses Changie to manage its CHANGELOG.md. This tool prevents merge conflicts by having contributors create individual YAML files for their changes instead of editing the main markdown file directly.

The Changie Process

1. New Entry: Contributors run changie new to create a change file in .changes/unreleased/.
2. Commit: The generated YAML file is committed with the Pull Request.
3. Merge: All merged changes are automatically aggregated into the next version during the release workflow.

Sources: CONTRIBUTING.md:129-138, CHANGELOG.md:1-8

Changelog Structure

The CHANGELOG.md is auto-generated and categorizes changes under specific headers:

• Breaking Changes: Requiring action from users or maintainers.
• Features: New functionality.
• Fixes: Bug resolutions.
• Under the Hood: Maintenance, dependency bumps, or internal refactors.

Sources: CHANGELOG.md:4-7, CHANGELOG.md:10-25

Dependency Versioning

The pyproject.toml file defines strict version bounds for dependencies to ensure stability. The build system uses hatchling and versioning is dynamic, pulling from dbt_common/__about__.py.

This sequence illustrates how the build system resolves the package version and dependencies before publishing.
Sources: pyproject.toml:1-5, pyproject.toml:96-98, pyproject.toml:139-141

Summary

dbt-common maintains a rigorous releasing and versioning strategy centered on semantic versioning and automated changelog generation. By utilizing hatch for project management and changie for change tracking, the project ensures that releases are predictable and compatible with the broader dbt ecosystem.

Sources: README.md:1-10, CONTRIBUTING.md:129-145