Principle:MaterializeInc Materialize Version Bumping
| Knowledge Sources | misc/python/materialize/release/cut_release.py, bin/bump-version |
|---|---|
| Domains | Release Engineering, Version Management, SBOM Generation |
| Last Updated | 2026-02-08 |
Overview
Automated version management systematically updates version identifiers across a multi-language codebase using a centralized bumping tool with SBOM generation.
Description
Version Bumping addresses the challenge of maintaining consistent version identifiers across a large, polyglot codebase. In a project like Materialize -- which spans Rust, Python, SQL, Docker, Helm charts, and documentation -- version numbers appear in dozens of locations: Cargo.toml files, Python package metadata, Dockerfile FROM directives, Helm chart manifests, and more. Manual updates are error-prone and incomplete.
The Materialize approach centralizes version bumping in a dedicated bin/bump-version tool that is executed inside a stable CI builder container via bin/ci-builder run stable. This ensures:
- Reproducibility: The CI builder container provides a consistent environment with all required tooling, regardless of the developer's local setup.
- Completeness: A single tool knows about all locations where version strings appear and updates them atomically.
- SBOM generation: The
--sbomflag triggers generation of a Software Bill of Materials alongside the version bump, ensuring that every release has a corresponding dependency manifest. - Separation of concerns: The
--no-commitflag prevents the tool from creating a git commit, delegating commit authorship to the calling script (which has the correct git author configuration). Similarly,--no-console-bumpprevents the tool from bumping the console version, since that is handled separately via the cross-repo coordination pattern.
Usage
Apply this principle when your project has version identifiers scattered across multiple files and languages. Centralize version management in a single tool that understands all locations, and invoke it within a controlled environment (container, CI, or virtual environment) to guarantee consistency. Include SBOM generation as part of the version bump to maintain supply chain transparency.
Theoretical Basis
The version bumping pattern addresses the scattered constant anti-pattern in software configuration. When the same logical value (a version number) is duplicated across many files without a single source of truth, updates become a coordination problem with O(n) manual steps and O(n) failure modes.
The centralized tool approach creates a single-writer model: one tool owns the responsibility of updating all version references. This is analogous to the single responsibility principle applied to build infrastructure.
The use of a containerized execution environment (ci-builder) follows the hermetic build principle from build system theory (as formalized in Bazel/Buck): build and release operations should depend only on declared inputs, not on the ambient environment. By running bump-version inside ci-builder run stable, the Materialize release process ensures that the tool has access to the correct versions of Rust, Python, and other dependencies regardless of the host machine's configuration.
The --no-commit flag implements the command-query separation principle: the version bumping tool modifies files (command) but does not commit them (a separate concern). This allows the calling script to control commit metadata (author, message) independently.