Specification

A clear and structured approach to software version management.

Introduction

In the world of software development, managing different versions across various stages of development, testing, and production can be complex. Without a clear system, it's easy to lose track of what a specific version represents, leading to confusion, deployment errors, and difficulties in tracking progress or issues. This is often compounded when dealing with multiple active development branches and varying levels of software maturity.

ZFVM (Zillowe Foundation Versioning Method) provides a comprehensive yet straightforward set of rules and guidelines for assigning and incrementing version identifiers. It builds upon the principles of Semantic Versioning (SemVer) by incorporating explicit information about the development Branch, the codebase's **Status, and an optional **Build identifier directly into the version string. This provides an immediate, clear understanding of a software version's context, stability, and intended use.

By adopting ZFVM, teams can:

• Clearly communicate the state and purpose of any given software version.
• Streamline coordination between development, QA, and operations.
• Improve traceability and management of software releases throughout their lifecycle.
• Provide multiple format options for different use cases and tools.

This document details the ZFVM V2 specification, providing a clear definition of its components and rules.

ZFVM V2 Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Format

A ZFVM version string, in its full canonical form, MUST take the form: [Branch] [Status] [X.Y.Z] [Build]

• The [Build] component is OPTIONAL.
• A single space MUST separate each component.
• No leading or trailing spaces are allowed for the overall string or individual components, except for the required separators.

2. Components

2.1. Branch

• The [Branch] component indicates the development environment or purpose.
• It MUST be one of the predefined branch identifiers (see Branches section).
• Each branch has a corresponding acronym for use in symbolic forms.
• Example: Dev (acronym: D), Prod (acronym: P), Spec (acronym: S), Pub (acronym: Pb).

2.2. Status

• The [Status] component indicates the maturity level of the codebase.
• It MUST be one of the predefined status identifiers, representing an ascending order of readiness (see Status Levels section).
• Each status has a corresponding acronym for use in symbolic forms.
• Example: Pre-Alpha (acronym: PA), Alpha (acronym: A), Beta (acronym: B), RC (acronym: RC), Release (acronym: R).

2.3. Semantic Version (X.Y.Z)

• The [X.Y.Z] component is a standard Semantic Version 2.0.0 number.
• X, Y, and Z MUST be non-negative integers and MUST NOT contain leading zeros (e.g. 1.2.3 is valid, 1.02.3 is not).
• X is the Major version. Y is the Minor version. Z is the Patch version.

2.4. Build

• The [Build] component is an OPTIONAL identifier that specifies a particular build instance of the software.
• It is intended for tracking specific compilations, such as from a CI/CD pipeline or a source control commit.
• The [Build] identifier formats include:
  • CI/CD run numbers: Non-negative integers (e.g. 1234, 9876)
  • Commit hashes: Short (7-8 characters) or full SHA hashes (e.g. a7d3c1f, a7d3c1f8b2e4d9c0)
  • Timestamps: ISO 8601 format or custom formats (e.g. 20240521T1430Z, 20240521-1430)
  • Custom identifiers: Alphanumeric strings without spaces (e.g. nightly-build, hotfix-123)
• The [Build] identifier MUST NOT contain spaces or other characters that would conflict with the ZFVM format.

3. Rules for Incrementing Semantic Version (X.Y.Z)

ZFVM adheres to standard SemVer rules for the X.Y.Z portion:

1. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
2. Version 1.0.0 defines the public API. The way the version number is incremented after this release is dependent on this public API and how it changes.
3. Patch version Z (e.g. x.y.Z where x > 0) MUST be incremented if only backward-compatible bug fixes are introduced.
4. Minor version Y (e.g. x.Y.z where x > 0) MUST be incremented if new, backward-compatible functionality is introduced to the public API. Patch version Z MUST be reset to 0 when minor version Y is incremented.
5. Major version X (e.g. X.y.z where X > 0) MUST be incremented if any backward-incompatible changes are introduced to the public API. Patch Z and minor Y versions MUST be reset to 0 when major version X is incremented.

4. Recommended Combinations

While the format allows any combination of defined Branch and Status, certain combinations are more logical and RECOMMENDED:

• Prod branch SHOULD typically be associated with Release status.
• Dev branch MAY use any status from Pre-Alpha through RC.
• Spec and Pub branches are typically used for testing and MAY use Alpha, Beta, or RC statuses.
• Using illogical combinations (e.g. Prod Pre-Alpha 1.0.0) SHOULD be avoided as it can cause confusion.

5. Alternative Version Forms

For flexibility, ZFVM supports several representations tailored to different use cases.

5.1. Full Form (Canonical)

[Branch] [Status] [X.Y.Z] [Build]

This is the complete, unambiguous representation of a version. It is the RECOMMENDED form for git tags, official release announcements, and any context where full traceability is required.

5.2. Contextual Form

[Status] [X.Y.Z]

This form omits the [Branch] and optional [Build]. It is useful in contexts where the branch is already known, such as within a CI/CD pipeline operating on a specific branch or in logs for a particular environment.

5.3. Semantic Form

[X.Y.Z]

This form consists of only the Semantic Version number. It is intended for use with dependency management tools (like npm, Cargo, etc.) that parse SemVer, or for contexts where only API compatibility is relevant.

5.4. Symbolic Form

ZFVM V2 provides two symbolic form options:

Option A (New): <branch-acronym>-<status-acronym>-<X.Y.Z>

• Uses branch and status acronyms for better readability
• Example: D-B-1.2.3 (Dev Beta 1.2.3), P-R-2.0.0 (Prod Release 2.0.0)

Option B (Legacy): b<n>s<m>-<X.Y.Z>

• Uses 1-based indices from the specification tables
• Example: b2s3-1.2.3 (Dev Beta 1.2.3), b1s5-2.0.0 (Prod Release 2.0.0)

Both forms are suitable for constrained environments like filenames, container tags, or URL slugs.

5.5. Shorthand Form

For common production releases, ZFVM V2 introduces shorthand notation:

• v<X> implies Prod Release <X>.0.0 (e.g. v1 = Prod Release 1.0.0)
• v<X.Y> implies Prod Release <X.Y>.0 (e.g. v1.2 = Prod Release 1.2.0)
• <X.Y.Z> alone implies Prod Release <X.Y.Z> (e.g. 1.2.3 = Prod Release 1.2.3)

This shorthand is particularly useful for public-facing version numbers and marketing materials.

6. Version Precedence

When comparing ZFVM versions, precedence follows this order:

1. Within the same branch and status: Standard SemVer precedence applies to the X.Y.Z component.
2. Within the same branch: Status levels have natural progression (Pre-Alpha < Alpha < Beta < RC < Release).
3. Across different branches: Context-dependent; typically Prod Release > Dev Release > other combinations.
4. Build component: Does not affect precedence; used only for traceability.

Branches

Each branch represents a specific development environment or purpose.

Status Levels

Status indicates the maturity of the codebase, in ascending order of readiness.

Examples

Full Form Examples:

• Dev Beta 1.2.3 456 - Development branch, beta status, with build 456
• Prod Release 2.0.0 - Production release without build identifier
• Pub Alpha 0.8.0 a7d3c1f - Public testing branch, alpha status, with commit hash

Symbolic Form Examples:

• D-B-1.2.3 (New format: Dev Beta 1.2.3)
• b2s3-1.2.3 (Legacy format: Dev Beta 1.2.3)
• P-R-2.0.0 (New format: Prod Release 2.0.0)
• b1s5-2.0.0 (Legacy format: Prod Release 2.0.0)

Shorthand Form Examples:

• v1 = Prod Release 1.0.0
• v1.2 = Prod Release 1.2.0
• 1.2.3 = Prod Release 1.2.3

Contextual Form Examples:

• Beta 1.2.3 (when branch is known from context)
• Release 2.0.0 (when branch is known from context)

Implementation Guide

For New Releases:

1. Determine the type of change (major, minor, or patch) and increment the X.Y.Z number accordingly.
2. Update the [Status] if the maturity level has changed.
3. Choose the appropriate [Branch].
4. Optionally, include a [Build] identifier from your build system.
5. Tag the repository with the Full Form of the new version string (e.g. git tag "Prod Release 1.5.1 1120").

For Tool Integration:

• Use Full Form for git tags and official documentation
• Use Contextual Form for CI/CD logs and environment-specific displays
• Use Semantic Form for dependency management tools
• Use Symbolic Form for container tags and file names
• Use Shorthand Form for public-facing version numbers

For Build Identifiers:

• CI/CD Systems: Use run numbers or job IDs
• Version Control: Use commit hashes (short or full)
• Nightly Builds: Use timestamps or "nightly" identifier
• Hotfixes: Use descriptive identifiers like "hotfix-123"

Visualization

Branch: [Prod|Dev|Spec|Pub] → Status: [Pre-Alpha → Alpha → Beta → RC → Release] → Version: X.Y.Z → Build: [ID]
                                                                                           ↑ ↑ ↑
                                                                                    Major ─┘ │ │
                                                                                    Minor ───┘ │
                                                                                    Patch ─────┘

Shorthand: v1 →    Prod Release 1.0.0
           v1.2 →  Prod Release 1.2.0
           1.2.3 → Prod Release 1.2.3

FAQ

Q1: What's new in ZFVM V2?

ZFVM V2 introduces several improvements:

• New symbolic form with acronyms for better readability (D-B-1.2.3 vs b2s3-1.2.3)
• Simplified status levels (removed Pre-Beta, Pre-Release, Early-Access, Demo)
• Shorthand notation for common production releases (v1, v1.2, 1.2.3)
• Enhanced build identifier guidelines
• Clear version precedence rules

Q2: How does ZFVM relate to Semantic Versioning (SemVer)?

ZFVM incorporates SemVer for the X.Y.Z part of its version string. It extends SemVer by adding [Branch] and [Status] prefixes to provide broader context about the software's development stage and environment, which SemVer alone does not cover.

Q3: When should I use the shorthand form?

Use shorthand form for:

• Public-facing version numbers on websites or marketing materials
• Simple production releases where context is clear
• When communicating with non-technical stakeholders
• Quick references in documentation

Avoid shorthand when:

• Full traceability is required
• Working with multiple branches
• In development or testing environments

Q4: Can I mix symbolic form options?

While both symbolic forms are valid, it's RECOMMENDED to choose one format and use it consistently within a project or organization. The new acronym-based format (D-B-1.2.3) is generally more readable, while the legacy index-based format (b2s3-1.2.3) is more compact.

Q5: How do I handle version precedence across different branches?

Version precedence across branches is context-dependent:

• For deployment decisions: Prod Release typically takes precedence
• For feature development: Compare within the same branch
• For dependency management: Use the semantic version component
• For build systems: Custom logic may be needed based on your workflow

Q6: What build identifier format should I use?

Choose based on your needs:

• CI/CD run numbers: Best for automated builds and traceability
• Commit hashes: Best for exact source code traceability
• Timestamps: Best for time-based releases (nightly builds)
• Custom identifiers: Best for special builds or hotfixes

Q7: How does the shorthand form work with version precedence?

Shorthand forms are equivalent to their full forms for precedence:

• v1 = Prod Release 1.0.0
• v1.2 = Prod Release 1.2.0
• 1.2.3 = Prod Release 1.2.3

Standard SemVer precedence applies: 1.0.0 < 1.1.0 < 1.2.0 < 1.2.3

Q8: When should I change the [Status]?

Change status as your codebase matures:

• Pre-Alpha → Alpha: Core functionality implemented
• Alpha → Beta: Feature complete, testing phase
• Beta → RC: Ready for release candidate testing
• RC → Release: Stable and production-ready

About

The Zillowe Foundation Versioning Method (ZFVM) was developed to provide a clear, comprehensive, and adaptable system for software versioning. ZFVM V2 builds upon the foundation of the original specification with improved usability, simplified status levels, and enhanced format options.

ZFVM extends Semantic Versioning (SemVer 2.0.0) to include critical context about the development branch and the maturity status of the software, addressing common challenges in managing complex software lifecycles.

ZFVM is designed and maintained by the Zillowe Foundation.

License

This Zillowe Foundation Versioning Method specification is licensed under the Apache 2.0 license.