ZFVM

A clear, flexible, and structured approach to software version management.

OverviewCopy Anchor Link

ZFVM (Zillowe Foundation Versioning Method) provides a standardized way to version software, ensuring clarity about its development stage, stability, and build history. It combines information about the development branch, the status of the code, a semantic version number, and an optional build number.

The full canonical format is:

[Branch] [Status] [X.Y.Z] [Build (optional)]

Where:

• Branch: The development environment, using a short identifier: Prod, Dev, Spec, or Pub.
• Status: The maturity level of the code: Pre-Alpha, Alpha, Beta, RC, or Release.
• X.Y.Z: The standard Major.Minor.Patch semantic version number.
• Build: An optional identifier for a specific build instance, such as a CI/CD run number or a commit hash.

Flexible Version FormsCopy Anchor Link

ZFVM is designed for versatility and supports multiple representations for different contexts:

• Full Form: [Branch] [Status] [X.Y.Z] [Build]
  • The complete, unambiguous version string. Ideal for release tagging and formal documentation.
• Contextual Form: [Status] [X.Y.Z]
  • Used when the branch is implied by the environment, for example within a development pipeline.
• Semantic Form: X.Y.Z
  • For tools and dependency managers that only understand standard SemVer. Carries no branch or status information, and is never interpreted as a ZFVM version.
• Symbolic Form: <branch-acronym>-<status-acronym>-X.Y.Z
  • A compact, space-free representation for constrained environments such as container tags, filenames, and URL slugs, for example D-B-1.2.3.
• Shorthand Form: v1, v1.2, v1.2.3
  • Implies Prod Release 1.0.0, Prod Release 1.2.0, and Prod Release 1.2.3 respectively. Intended for public-facing version numbers.

The Status LadderCopy Anchor Link

A ZFVM version climbs the status ladder at a fixed version number, gaining confidence before anything changes:

Dev Pre-Alpha 1.4.0  →  Dev Alpha 1.4.0   →  Dev Beta 1.4.0  →  Dev RC 1.4.0  →  Prod Release 1.4.0
Dev Beta 1.5.0       →  Dev RC 1.5.0      →  Prod Release 1.5.0

X.Y.Z advances only when the software actually changes, following the standard SemVer rules. This keeps the status ladder a tool for progressive delivery rather than a second version counter that moves independently.

Working with SemVerCopy Anchor Link

ZFVM requires a SemVer core version, but the full ZFVM string is not itself valid SemVer. The specification defines a normative projection back onto SemVer, using numeric status ordinals so that SemVer precedence preserves ZFVM status precedence:

Numeric ordinals are used because SemVer sorts pre-release identifiers numerically before it sorts them lexically, so a readable -pre-alpha would incorrectly sort after -beta. The branch has no representation in SemVer and should be recorded separately by your tooling.

Why ZFVM?Copy Anchor Link

In today's complex software development landscape, managing multiple versions, features, and deployment environments can quickly become chaotic. ZFVM addresses this by:

• Providing Clarity: the format offers an at-a-glance understanding of a software version's context.
• Standardizing Communication: ZFVM establishes a common language for development teams, QA, and stakeholders.
• Facilitating Broader Context: while SemVer (X.Y.Z) handles API compatibility, ZFVM adds layers for branch, status, and build, crucial for internal development cycles and staged rollouts.
• Supporting Diverse Workflows: ZFVM's flexible forms adapt to various use cases, from CI/CD logs to public-facing dependency manifests.
• Improving Traceability: encoding the development stage, branch, and build into the version string aids in tracking issues and managing deployments.

ZFVM aims to bring the rigor of Semantic Versioning to the broader context of the software development lifecycle.

ExamplesCopy Anchor Link

Here are a few examples of ZFVM in practice:

• Dev Beta 1.2.3 987: a beta release on the development branch, from build 987.
• Prod Release 1.5.0: the stable production release.
• Prod Release 1.5.1 1120: a patch release to production for bug fixes, from build 1120.
• Pub Alpha 0.8.0 a7d3c1f: a public testing release, from commit a7d3c1f.
• D-B-1.2.3: the Symbolic Form for Dev Beta 1.2.3.
• v1.5.1: shorthand for Prod Release 1.5.1.

ConformanceCopy Anchor Link

The specification defines a formal grammar and separate obligations for parsers, producers, comparators, and mappers, so that tools built on ZFVM can be tested for interoperability. A conforming parser accepts the Full and Contextual Forms and rejects anything that does not match the grammar.

Full Specification and GuideCopy Anchor Link

For the complete Zillowe Foundation Versioning Method specification, including the formal grammar, conformance requirements, SemVer mapping, precedence rules, changelog, and a comprehensive FAQ, please see the full document:

-> ZFVM Specification and Guide

LicenseCopy Anchor Link

The ZFVM specification text is licensed under CC BY-SA 4.0, SPDX identifier CC-BY-SA-4.0.