Changelog & Release Process
Relevant source files
The following files were used as context for generating this wiki page:
The Changelog and Release Process for the dbt-adapters monorepo is designed to manage high-velocity updates across multiple independent yet related Python packages. Because the repository contains the base framework, a shared test suite, and several first-party adapters (Postgres, Snowflake, BigQuery, etc.), the process relies on automated tooling to ensure consistency and a branched stability model to manage minor and patch releases simultaneously.
Sources: README.md:18-32, CONTRIBUTING.md:42-53
Changelog Management with Changie
This project uses Changie to manage its changelogs. Instead of editing CHANGELOG.md files directly, contributors generate small YAML fragments for each change. These fragments are then collated and injected into the appropriate changelogs during the release process.
Creating a Changelog Entry
When a Pull Request (PR) is created, the contributor must run the changie new command from their local environment. This interactive tool prompts for the type of change and a description.
Sources: CONTRIBUTING.md:139-152, AGENTS.md:137-142
Change Categories
Changes must be classified into one of the following standard categories supported by the monorepo:
| Category | Description |
|---|---|
| Breaking Changes | Changes that require action from end users or external maintainers when upgrading. |
| Features | New functionality or capabilities added to the adapter or framework. |
| Fixes | Bug fixes and corrections to existing logic. |
| Under the Hood | Internal refactoring, performance improvements, or non-user-facing logic changes. |
| Dependencies | Updates to required libraries or version pins. |
| Security | Security-related patches and vulnerability resolutions. |
Sources: AGENTS.md:144, dbt-adapters/CHANGELOG.md:10-15
Collation Flow
The following diagram illustrates how individual change fragments become part of the final release documentation.
Note: Any manual edits to CHANGELOG.md will be lost during the consolidation process.
Sources: CONTRIBUTING.md:144-154
Release Branches and Promotion
The monorepo employs a specific branching strategy to separate ongoing development for future minor releases from stable patch updates.
Stable vs. Main
mainbranch: Hosts the next minor release (e.g., v1.12.0). Most development occurs here.stablebranch: Hosts the current minor version (e.g., v1.11.x). Patch releases are cut from this branch.
Except for dbt-adapters and dbt-tests-adapter, merging a PR to main does not automatically queue it for immediate release. To include a merged change in a release, maintainers must add the promote to stable label to the PR.
Sources: README.md:38-46
Release Process Flow
Note: This architecture allows the team to patch previous minor versions while preparing the next major/minor release.
Sources: README.md:43-51
Package Release Versions
Each package in the monorepo is versioned independently but follows Semantic Versioning. Current planned minor releases are tracked via GitHub milestones.
| Package | Planned Version | Subdirectory |
|---|---|---|
| dbt-adapters | 1.24.x | /dbt-adapters |
| dbt-tests-adapter | 1.20.x | /dbt-tests-adapter |
| dbt-athena | 1.11.0 | /dbt-athena |
| dbt-bigquery | 1.12.0 | /dbt-bigquery |
| dbt-snowflake | 1.12.0 | /dbt-snowflake |
Sources: README.md:53-64, dbt-adapters/CHANGELOG.md:18
Automated Verification
The release process is gated by automated checks configured at the repository level. Before any change can be considered for release (and before changie entries are finalized), the following must pass:
- Code Quality:
hatch run code-quality(runs Black, Flake8, and MyPy). - Unit Tests:
hatch run unit-tests(logic validation without database). - Integration Tests:
hatch run integration-tests(functional validation against live databases).
Sources: AGENTS.md:37-65, CONTRIBUTING.md:95-114
Summary
The "Changelog & Release Process" ensures that every user-facing change is documented via changie and verified through a rigorous monorepo testing suite. By utilizing a "promote to stable" labeling system, the project maintains a high-quality stable branch for immediate patches while allowing the main branch to iterate on significant framework and adapter enhancements for future minor releases.