Implementation:MaterializeInc Materialize Cut Release Verify

Knowledge Sources	misc/python/materialize/release/cut_release.py (lines 31-60)
Domains	Release Engineering, CLI Tooling, Python
Last Updated	2026-02-08

Overview

Concrete argument parsing and prerequisite verification entry point provided by the cut_release module in Materialize's release tooling.

Description

The main() function in cut_release.py serves as the entry point for cutting a new Materialize release. The initial portion of this function (lines 31-60) handles:

1. Argument parsing via argparse.ArgumentParser with three required arguments:
   • --sha: The git commit SHA to release from (type str).
   • --version: The semantic version string (parsed via parse_version() which strips a leading v and delegates to semver.version.Version.parse()).
   • --remote: The git remote name for the Materialize repository (type str).
2. Docker availability check by running docker info via spawn.capture().
3. Branch state recording by calling get_branch_name() to save the current branch before checking out the release SHA.
4. SHA checkout by calling checkout(args.sha) within a try/finally block that guarantees the original branch is restored.

Usage

Use this implementation reference when you need to understand the entry point for Materialize's release cutting process, the required CLI arguments, or the prerequisite checks that gate the release. This is the first phase executed when cut_release is invoked.

Code Reference

Source Location

misc/python/materialize/release/cut_release.py, lines 31-60.

Signature

def main() -> None:
    parser = argparse.ArgumentParser(
        prog="cut_release",
        description="Creates a new release for Materialize.",
    )
    parser.add_argument("--sha", help="Chosen SHA of the release", type=str, required=True)
    parser.add_argument("--version", help="Version of release", type=parse_version, required=True)
    parser.add_argument("--remote", help="Git remote name of Materialize repo", type=str, required=True)
    args = parser.parse_args()
    version = f"v{args.version}"
    current_branch = get_branch_name()
    print("Checking if Docker is running")
    spawn.capture(["docker", "info"])
    try:
        print(f"Checking out SHA {args.sha}")
        checkout(args.sha)
        ...
    finally:
        if current_branch:
            checkout(current_branch)

Import

from materialize.release.cut_release import main

I/O Contract

Inputs

Parameter	Type	Required	Description
--sha	str	Yes	The git commit SHA to build the release from
--version	semver.version.Version (via parse_version)	Yes	Semantic version string (e.g., v0.79.0)
--remote	str	Yes	Git remote name pointing to the upstream Materialize repo

Outputs

Output	Type	Description
Git working tree state	Side effect	The working tree is checked out to the specified SHA
Docker validation	Side effect	Raises subprocess.CalledProcessError if Docker is not running
Branch restoration	Side effect	Original branch is restored in the finally block

Usage Examples

Invoking from the command line:

python -m materialize.release.cut_release \
    --sha abc123def456 \
    --version v0.79.0 \
    --remote origin

Calling programmatically (for testing):

import sys
sys.argv = [
    "cut_release",
    "--sha", "abc123def456",
    "--version", "v0.79.0",
    "--remote", "origin",
]
from materialize.release.cut_release import main
main()

Helper function used for version parsing:

from materialize.release.cut_release import parse_version
v = parse_version("v0.79.0")
# Returns: Version(major=0, minor=79, patch=0)

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Release_Prerequisite_Verification