Heuristic:Duckdb Duckdb Version Sync Across Files
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Release_Management |
| Last Updated | 2026-02-07 12:00 GMT |
Overview
The `MAIN_BRANCH_VERSIONING` flag must be kept in sync across three files (CMakeLists.txt, amalgamation.py, package_build.py) to avoid version mismatches in builds.
Description
DuckDB's versioning system uses a `MAIN_BRANCH_VERSIONING` flag that controls whether the build uses main-branch versioning (matching `v*.*.0` tags) or release-branch versioning (matching `v*.*.*` tags). This flag is defined independently in three separate files and must be manually kept in sync. A mismatch causes the build version to differ between the CMake build, the amalgamation, and the source package.
Usage
Apply this heuristic when creating release branches, modifying version tagging behavior, or debugging version mismatches between DuckDB builds. If the version reported by a CMake build differs from the amalgamation version, this flag being out of sync is the likely cause.
The Insight (Rule of Thumb)
- Action: When changing `MAIN_BRANCH_VERSIONING`, update all three files simultaneously:
- `CMakeLists.txt` (line 253)
- `scripts/amalgamation.py` (lines 282-285)
- `scripts/package_build.py` (corresponding lines)
- Value for main/feature branches: `TRUE`
- Value for release branches: `FALSE`
- Trade-off: Manual synchronization required; no automated enforcement.
Reasoning
The three files independently compute the DuckDB version string. If `MAIN_BRANCH_VERSIONING` differs between them, the CMake build might compute `v1.2.0-dev123` while the amalgamation computes `v1.2.3-dev123`, leading to confusing version mismatches in distributed artifacts.
Code evidence from `CMakeLists.txt:245-256`:
set(VERSIONING_TAG_MATCH "v*.*.*")
######
# MAIN_BRANCH_VERSIONING default should be 'TRUE' for main branch and feature branches
# MAIN_BRANCH_VERSIONING default should be 'FALSE' for release branches
# MAIN_BRANCH_VERSIONING default value needs to keep in sync between:
# - CMakeLists.txt
# - scripts/amalgamation.py
# - scripts/package_build.py
######
option(MAIN_BRANCH_VERSIONING "Versioning scheme for main branch" TRUE)
if(${MAIN_BRANCH_VERSIONING})
set(VERSIONING_TAG_MATCH "v*.*.0")
endif()
Shallow clone fallback from `CMakeLists.txt:347-349`:
if (GIT_RESULT)
message(WARNING "git is available but has failed to execute 'describe --tags --long',
likely due to shallow clone. Consider providing explicit OVERRIDE_GIT_DESCRIBE
or clone with tags. Continuing with dummy version v0.0.1")
set(GIT_DESCRIBE "v0.0.1-0-g${GIT_COMMIT_HASH}")
endif()