Principle:MaterializeInc Materialize Version Resolution
| Knowledge Sources | misc/python/materialize/checks/scenarios_upgrade.py, misc/python/materialize/version_list.py |
|---|---|
| Domains | Version Management, Upgrade Testing, Compatibility Testing |
| Last Updated | 2026-02-08 |
Overview
Dynamic version resolution discovers available Materialize releases from multiple sources (git tags, Docker Hub, Helm charts) to construct valid upgrade paths for compatibility testing.
Description
Upgrade testing requires knowing which versions exist and which versions are valid starting points for an upgrade to the current version. The Version Resolution principle addresses this by defining a layered resolution strategy:
- Git tag enumeration — All Materialize versions are tagged in the git repository using semantic versioning (e.g.,
v0.130.0). The version list module enumerates these tags and filters out invalid or pre-release versions. - Docker image validation — Not every tagged version has a corresponding published Docker image. The resolution pipeline verifies that a Docker image exists before accepting a version as usable, skipping versions whose images were never published or have been removed.
- Helm chart enumeration — For self-managed deployments, versions are also resolved from the Helm chart index at the public Materialize Helm repository. This ensures that the upgrade tests cover the versions that self-managed customers actually use.
- Minor version aggregation — To keep the test matrix manageable, the framework selects the latest patch for each minor version rather than testing every individual patch release. This provides minor-version-level coverage without combinatorial explosion.
The resolution is lazy and cached: version lists are computed on first access and stored in module-level globals to avoid repeated expensive operations (Docker image pulls, HTTP requests to Helm indices, git tag enumeration).
A set of invalid versions is maintained as a hardcoded denylist (INVALID_VERSIONS and BAD_SELF_MANAGED_VERSIONS) to exclude versions known to be broken or incompatible with upgrade testing.
Usage
Apply this principle whenever you need to:
- Determine the starting version for an upgrade scenario (e.g., "upgrade from the last minor version").
- Enumerate all valid upgrade-from versions within a supported window.
- Filter versions by publication status, Docker image availability, or Helm chart presence.
- Understand why a specific version is excluded from upgrade testing.
Theoretical Basis
Version resolution for upgrade testing is an instance of the constraint satisfaction problem over a partially ordered set of software releases. The constraints are:
- Temporal ordering — Versions form a total order via semantic versioning. Upgrades must go from a lower version to a higher version.
- Availability — Only versions with published artifacts (Docker images, Helm charts) can be tested.
- Compatibility — Certain versions are known to be incompatible with upgrade testing due to catalog migration bugs or other issues.
- Recency — The testing window is bounded (e.g., within one major version of the current release) to keep test times manageable.
The resolution algorithm applies these constraints as successive filters:
all_git_tags
|-- filter: exclude INVALID_VERSIONS
|-- filter: exclude pre-release versions
|-- filter: select latest patch per minor version
|-- filter: verify Docker image exists
|-- result: list of usable versions for upgrade testing
For self-managed versions, an additional path through the Helm chart index provides an independent version source that is intersected with the git-tag-based list.