Version Schema

Version: Experimental.0 {VSchemaInDev.0}

Summary

VersionSchema is a proposed standard schema for declaring the syntax and semantics of any version string, or (aspirationally) XML, JSON or YAML record containing version data. The current focus is on defining version string syntax and semantics. A version schema is meant to convey; both human, and machine readable, information regarding the syntax and business rules (semantics), applied to any version data that includes a Version Meta tag. This project is an early work-in-progress and no standard schema has been settled on. We have one experimental XML schema and some example Version Schema based on that XSD ready for comment. Oxygen XML (link) docs available here. A GitHub project has been setup to track artifacts, progress, and take feedback.

The subtitle and browser window/tab title of this page; both contain a URI within curly braces that is a Version Meta tag, that points to the version schema in use for versioning the current VersionSchema XSD file. A full description of that schema can be read here.

Introduction

A version schema is any XML file containing only elements defined in the official VersionSchema XSD file. The current version under development is versionschema.experimental.next.xsd. Oxygen XML (link) docs available here. Tooling to process VersionSchema's is a work-in-progress, but not currently ready for any kind of review.

Past Present and Future

Probably the best known and oldest artifacts that version numbers are applied to, are books. Publishers call them revisions, and they have employed variations of at least several schemes; ranging from dates, a single integer (rev 1, rev2, etc), through "decimal" revisions (1, 1.2, etc) to more complicated schemes incorporating digits, letters of the alphabet and other symbols. In the realm of computer software, the earliest version schemes often followed whatever scheme the engineering department used to version their circuit board designs and other products.

The current best practice for software, is to use SemVer, but few actually use it correctly and most would prefer to have it modified to also accept any one of a dozen variations. Part of the problem has to do with the variety of things that must be versioned. SemVer is tied, by definition, to API's and any associated packages containing implementations of those API's. While nobody can blame the keepers of the SemVer standard for their rightfully narrow focus, the universe contains a much wider array of artifacts that require versioning of one kind or another. In addition, there's a wide range of common practices with regard to the prerelease and build meta tags in use and there is no common method for conveying the semantic details embedded in those practices.

VersionSchema represents a possible next step in the evolution of version strings. If successful, we will no longer be locked into pseudo-standards that are barely more than least common denominators. In the near future, you should be able to use a range of version schemata for different purposes, such as internal test releases, early adopter (flight testing), wider public releases, etc. Use one schema for your documents or art work and another for your software. In every case, the same set of tooling can be used in your build/publish pipelines, no matter what semantics are applied to the version strings in use.

Goals

Aspirations

Scenarios

VersionMeta and VersionSchema combined, enable a plurality of scenarios that can be applied individually or in sequence, to support a variety of work-flows across a wide range of organizations. We're maintaining a growing set of example schema to highlight features of VesionSchema. The following scenarios describe how VersionMeta and VersionSchema can be combined for practical use.

Continuous Integration

Automated continuous integration is a defining DevOps process. Automation produces a build for every submission/merge, to a designated repository, and then publishes a package for internal testing and possibly wider audiences. These builds are often not considered to be "official releases", but often do find their way into more or less public feeds. It's a common practice for these build products to retain the version number of the previously publically released, or the intended target version, but this leads to many packages with different content that have the same version strings. To avoid this, many CI build systems simply append a prerelease tag and build number to the version information. If/when QA signs-off on a build product, the prerelease tag is removed and the product is made available on an appropriate public feed.

With VersionMeta and VersionSchema, you don't have to force-fit any one version scheme to fit every stage of your processes. Instead, you have something like our simple build counter schema and your version strings have the form:

    # {SimpleCounter}
    

The undefined assurances declared by this schema indicate that it is potentially unstable and the total form of the version string make it obvious it's not an "official release" of any kind. Additionally, an organization could deploy different schema's for flight-test releases, release-candidates and official releases.

Product Prerelease

Product prereleases have a wide variety of version string formats. They range from one or more integer fields, to strings of tags/identifiers and combinations thereof. VersionMeta and VersionSchema provide a clear indication of which scheme is in use and any quality or compatibility assurance claims of the publisher.

For software components, semantic versioning is one of the more popular version formats in use today. It is supported by a variety of tools and well understood in the software development community. We have created an unofficial first draft schema for SemVer 2.0.0. A proposed version string might have the form:

    #.#.#-prerelease+optional.build.meta {SemVer.2.0.0}
    

Product Release

Again semantic versioning comes to mind:

    #.#.#+optional.build.meta {SemVer.2.0.0}
    

Hybrids

Given a hypothetical organization X, any number of schema can be deployed across the full variety of publications:

Website

    YYYY.MM.DD.HH.MM {UTC.Timestamp}
    

Book

    ########## {ISBN10}
    ############# {ISBN13}
    

GUI

      #.# {Version.Patch}
    

CI build artifact

    # {https://X.org/SimpleCounter}
    
Last updated 2018-08-29 12:38 UTC