@page versioning  Version Numbering


Numbering Scheme
================

UberPOV **source code** version numbers have the form `A.XY.Z.B`[`-PRE`], where:

  - `A` is the UberPOV major version number, and is intended to indicate radical changes.
  - `XY.Z` are the major, minor and sub-minor version numbers of the official POV-Ray release on which this UberPOV
    version is based; e.g. `37.1` indicates POV-Ray version `3.7.1` as the basis.
  - `B` is an additional UberPOV-specific sub-minor version number, to allow for incrementing the version number while
    the underlying POV-Ray version remains the same.
  - `PRE`, if present, is a pre-release identifier comprised of alphanumeric and numeric fields separated by dots
    (`.`), indicating that the version is a forerunner to, but may still differ in functionality from, what will
    ultimately become the official release `A.XY.Z.B`, and that the version should not be used in a production
    environment. It typically has one of the following forms:
      - `PHASE.ID`, with `PHASE` being one of `alpha`, `beta` or `rc`, indicates that the version is part of the
        main line of development in the respective phase of the development cycle.
      - `x.FEATURE.ID` indicates that the version is part of a side line of development, uniquely identified by the
        alphanumeric moniker `FEATURE`, which may ultimately contribute to the main line, but in its current state is
        deemed unfit to be included for one reason or another.
      .
    In both cases `ID` is a numeric value uniquely distinguishing the pre-release in question from other pre-releases
    of that same phase or side line.

@note
    Due to the semantics of the `#version` directive and `version` pseudo-variable, both the `Y` and `Z` portions of
    the version number are restricted to single digits.

UberPOV **build** version numbers have the form `A.XY.Z`[-`PREB`][`+BUILD`], where:

  - `A.XY.Z` matches the corresponding portion of the source code version.
  - `PREB` generally matches the `PRE` portion of the source code version, except that it always contains an
    additional `unofficial` entry (separated from the `PRE` portion by a dot if applicable) unless the UberPOV
    maintainers have officially authorized the build for public distribution.
  - `BUILD`, if present, is an alphanumeric identifier uniquely distinguishing a particular build from other builds
    based on the very same source code version. For example, automated builds generated by the AppVeyor service on
    behalf of the UberPOV maintainers may carry build identifiers of the form `avN`, where `N` is a running numeric
    value.


What To Change
==============

When updating a version number, the following files need to be changed accordingly:

  - `unix/VERSION`
  - `source/base/branch.h`

@note
    The version numbers in `source/base/version.h` identify the underlying official version of POV-Ray, and should be
    carried over from the official sources without modification.

@warning
    When updating the minor or major version number, a host of other files need to be changed as well.


Automatic Version Numbering
===========================

The directory `tools/git/hooks` contains scripts intended to (among other things) help with version numbering when using
Git; to benefit from them, copy them to the `.git/hooks` directory in your local Git workspace. Whenever you perform a
commit, they will automatically take care of the following:

  - Verify that `unix/VERSION` and the various version number variants in `source/base/branch.h` match.
  - Update the `ID` portion of pre-release versions whenever any files in one of the following directory sub-trees have
    been staged for commit: `source`, `vfe`, `platform`, `mac`, `unix`, `windows` or `libraries`. The new value of the
    `ID` portion will be the number of minutes elapsed since 2000-01-01 00:00 UTC.
