Principle:MaterializeInc Materialize Release Commit and Tagging
| Knowledge Sources | misc/python/materialize/release/cut_release.py, misc/python/materialize/git.py |
|---|---|
| Domains | Release Engineering, Version Control, Git Tagging |
| Last Updated | 2026-02-08 |
Overview
Atomic release point creation uses annotated git tags to create immutable, verifiable release points in version control history.
Description
Release Commit and Tagging is the principle of creating a single, atomic commit that captures all version-bumped changes, followed by an annotated git tag that marks that commit as a release point. This ensures that every release corresponds to exactly one commit in the repository history, and that commit is unambiguously identified by a semantic version tag.
In the Materialize release workflow, this principle manifests as a three-step sequence:
- Commit all changes: After version bumping (both via
bump-versionand the inline Dockerfile/Helm updates), all modifications are committed together with the message"release: bump to version {version}"usinggit commit -am. The-aflag stages all modified tracked files, ensuring nothing is accidentally left out. - Create an annotated tag: The
tag_annotated(version)function frommaterialize.gitcreates an annotated tag (usinggit tag -a -m {tag} {tag}). Annotated tags, unlike lightweight tags, store the tagger identity, timestamp, and a message, making them suitable for release identification. - Push the tag: The tag is pushed to the specified remote using
git push {remote} {version}. This is a deliberate, targeted push of only the tag -- not the branch -- since the release is built from a detached HEAD at the specified SHA.
The use of annotated (rather than lightweight) tags is significant: annotated tags are full git objects with their own SHA, author, date, and message. They are the recommended tag type for releases because they provide an audit trail and are required by many git-based tooling conventions (e.g., git describe ignores lightweight tags by default).
Usage
Apply this principle in any release workflow where you need an immutable, verifiable marker in version control history. Use annotated tags (not lightweight tags) for releases. Commit all version changes atomically in a single commit before tagging. Push only the tag to the remote, not the branch, when building from a detached HEAD.
Theoretical Basis
The release tagging pattern implements several fundamental version control concepts:
Atomic commits: By committing all version-bumped files in a single git commit -am, the release creates an atomic changeset -- either all version references are updated, or none are. This maps to the all-or-nothing property of transactions in database theory.
Immutable references: An annotated git tag is an immutable pointer to a specific commit. Once pushed, it serves as a stable reference that CI/CD pipelines, deployment systems, and users can rely on. Attempting to move an annotated tag produces a warning, reinforcing its intended permanence.
Separation of content and metadata: The commit contains the content changes (version bumps), while the annotated tag adds metadata (release version, tagger, timestamp). This separation follows the principle of orthogonal concerns -- the same commit could theoretically be tagged with multiple labels (e.g., both v0.79.0 and latest-stable).
Push minimality: Pushing only the tag (git push remote version) rather than the branch follows the principle of least authority (POLA). The release script modifies the working tree at a detached HEAD and only publishes the specific artifact (the tag) needed to trigger downstream release pipelines, avoiding unintended branch mutations.