Updated AppVeyor config.

- Remove the `+avN` postfix from generated release tags.
- Automatically flag builds as experimental if their version number has a prefix beginning with `-x`, e.g. `3.7.1-x.foo.8765432`.

Also updated the developers' documentation on version numbering.

Author: c-lipka

appveyor.yml

@@ -55,7 +55,23 @@ build:
 after_build:
 - ps: |
     $env:pov_exe_version = (Get-Content unix\VERSION)
-    $env:pov_version = "v" + $env:pov_exe_version + '+av' + $env:APPVEYOR_BUILD_NUMBER
+    $env:pov_tag_version = 'v' + $env:pov_exe_version
+    $env:pov_build_version = $env:pov_tag_version + '+av' + $env:APPVEYOR_BUILD_NUMBER
+    $env:pov_build_message = ''
+    if ($env:pov_exe_version -match '^[0-9.]*-x') {
+      $env:pov_build_type = 'Experimental'
+      $env:pov_build_message += '**EXPERIMENTAL: This version of POV-Ray is not part of the official development branch!**'
+      $env:pov_build_message += "`n`n"
+    } elseif ($env:pov_exe_version -match '^[0-9.]*-') {
+      $env:pov_build_type = 'Development'
+    } else {
+      $env:pov_build_type = 'Automated'
+    }
+    $env:pov_release_type = ($env:pov_build_type).ToLower() + ' release'
+    $env:pov_build_title = $env:pov_build_type + ' build'
+    $env:pov_build_message += '**Note:** This is a binary-only ' + $env:pov_release_type + '; to install, copy the binary into an existing POV-Ray 3.7 installation. (Make sure to backup the original binary first.)'
+    $env:pov_build_message += "`n`n"
+    $env:pov_build_message += 'The 64-bit binary may require Windows Vista or higher. To run this ' + $env:pov_release_type + ' on an earlier 64-bit version of Windows, you may need to use the 32-bit SSE2 binary instead.'
     $env:pov_zipdir = "povray-" + $env:pov_exe_version + '-av' + $env:APPVEYOR_BUILD_NUMBER + $env:artifact_suffix
     $env:pov_binary = "Windows\vs10\" + $env:bin_dir + "\pvengine*.exe"
     $env:pov_zip = "artifacts\" + $env:pov_zipdir + ".7z"
@@ -73,11 +89,8 @@ artifacts:
 deploy:
 - provider: GitHub
   tag: $(pov_version)
-  release: Development build $(pov_version)
-  description: |-
-    **Note:** This is a binary-only development release; to install, copy the binary into an existing POV-Ray 3.7 installation. (Make sure to backup the original binary first.)
-    
-    The 64-bit binary may require Windows Vista or higher. To run this development release on an earlier 64-bit version of Windows, you may need to use the 32-bit SSE2 binary instead.
+  release: $(pov_build_title) $(pov_build_version)
+  description: $(env:pov_build_message)
 
   auth_token:
     secure: WkcFPXyr/SJ9TXixTQyivhfoR9FzlryIbc4deHeQ0eA6YRXL0wQopMYJ6XL1/FJK

source-doc/versioning.md

@@ -1,8 +1,14 @@
 # Version Numbering {#versioning}
 
-@section schm       Numbering Scheme
+Numbering Scheme {#versioning_schm}
+================
 
-Official POV-Ray builds have version numbers of the form `X.Y.Z`[`-PRE.ID`], where:
+The current POV-Ray version numbering scheme is designed to comply with the format and precedence rules of
+[Semantic Versioning v2.0.0](http://semver.org/spec/v2.0.0.html). However, it differs notably in the semantics of the
+third field of the version number (referred to as _patch version_ in the Semantic Versioning standard), as well as
+in a few special uses of the _pre-release_ field.
+
+POV-Ray **source code** version numbers have the form `X.Y.Z`[-`PRE`], where:
 
   - `X` is the major version number, and is intended to indicate radical changes, such as the planned redesign of the
     scene description language (SDL).
@@ -11,29 +17,55 @@ Official POV-Ray builds have version numbers of the form `X.Y.Z`[`-PRE.ID`], whe
     version number.
   - `Z` is a sub-minor version number, and is primarily intended to indicate addition of, or changes in, minor features,
     so that they can be tested for from the SDL.
+  - `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 `X.Y.Z`, 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.
 
-  - `PRE` is a pre-release identifier, such as `alpha`, `beta` or `rc`, indicating that it is a forerunner to, but may
-    still differ in functionality from, what will ultimately become the official version `X.Y.Z`.
-  - `ID` is a numeric value uniquely distinguishing the pre-release in question from other pre-releases.
+POV-Ray **build** version numbers have the form `X.Y.Z`[-`PREB`][`+BUILD`], where:
 
-Unofficial builds should have version numbers of the form `X.Y.Z-`[`PRE.ID.`]`unofficial`.
+  - `X.Y.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 POV-Ray dev
+    team has 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 POV-Ray team carry build identifiers of the form `avN`, where `N` is a running numeric value.
 
 
-@section chng       What To Change
+What To Change {#versioning_chng}
+==============
 
 When updating a version number, the following files need to be changed accordingly:
 
   - `unix/VERSION`
-  - `source/backend/povray.h`
+  - `source/base/version.h`
+
+@warning
+    When updating the minor or major version number, a host of other files need to be changed as well.
 
 
-@section auto       Automatic Version Numbering
+Automatic Version Numbering {#versioning_auto}
+===========================
 
 The directory `tools/git/hooks` contains scripts intended to 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 care of the following:
+automatically take care of the following:
 
-  - Verify that `unix/VERSION` and the various version number variants in `source/backend/povray.h` match.
+  - Verify that `unix/VERSION` and the various version number variants in `source/base/version.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`, `mac`, `unix`, `windows` or `libraries`.
+    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.