Principle:MaterializeInc Materialize Release Completion

Knowledge Sources	misc/python/materialize/release/mark_release_complete.py, misc/python/materialize/release/util.py
Domains	Release Engineering, Documentation, Release Lifecycle Management
Last Updated	2026-02-08

Overview

Release lifecycle finalization marks a release as complete in documentation and metadata after all deployment steps have succeeded.

Description

Release Completion is the principle of explicitly transitioning a release from an in-progress state to a completed state by updating documentation metadata. In Materialize's release lifecycle, a release progresses through distinct phases:

1. Cutting: The release is cut by creating a version tag and pushing it (handled by cut_release.py).
2. Testing/RC: Release candidates may be published and tested. During this phase, the release's documentation frontmatter may contain an rc field indicating the current release candidate number.
3. Complete: Once all validation passes, the release is marked as complete by setting released: true in the documentation frontmatter.

The completion step involves modifying YAML frontmatter in a Markdown documentation file located at doc/user/content/releases/{version}.md. The frontmatter uses the python-frontmatter library for structured parsing and serialization. Key operations include:

• Setting released: true in the frontmatter metadata.
• Setting the patch field to the final patch number.
• Removing the rc field if present (since the release is no longer a candidate).
• Committing and pushing the change to the main branch.

This metadata is consumed by the documentation site generator to control which releases are displayed as available, their ordering, and their status indicators.

Usage

Apply this principle when your release process has distinct lifecycle phases (cutting, testing, GA) and you need a machine-readable mechanism to track which phase each release is in. Use structured metadata (YAML frontmatter, database records, or API state) rather than relying on implicit signals (like the presence of a tag) to determine release status.

Theoretical Basis

Release completion implements a finite state machine for release lifecycle management:

[Cutting] --> [RC/Testing] --> [Complete]
                  |                |
                  v                v
              (rc: N)        (released: true)
              (released:     (patch: N)
               false/absent) (rc: removed)

The state transitions are:

• Cutting -> RC: Triggered by cut_release.py creating the tag. The documentation file may have rc: 1 in its frontmatter.
• RC -> Complete: Triggered by mark_release_complete.py setting released: true and removing rc.

This state machine is persistent -- it is stored in git-tracked files rather than ephemeral process memory. This means:

• The release state survives process restarts and is visible to all team members.
• State transitions are auditable through git history.
• The state can be queried by any tool that can read the documentation files.

The use of YAML frontmatter as the state store follows the infrastructure as code philosophy: release metadata lives alongside the release documentation in version control, eliminating the need for an external release management database.

The commit-and-push at the end of the completion step ensures that the state transition is durable and visible -- it is propagated to the remote repository and will be picked up by CI/CD pipelines and documentation builds.

Related Pages

Implemented By

• Implementation:MaterializeInc_Materialize_Mark_Release_Complete_Main