====== Version Numbering ======

===== Overview of Version Numbers =====
Processing Modules often change over time. We want to classify the
possible types of changes based on their effect on the produces
output datasets. We need to consider three types of changes for modules:
  * changes that preserve the output dataset values and format,
  * changes that produce different output dataset values but preserve the output dataset format, and
  * changes that produce different output dataset values and different output dataset format.

Typically, these differences in result datasets stem from the
following sourcecode changes for the module:
  * preserve all:
  *   * typically a change in coding style, runtime, or documentation
  * change values but preserve format:
  *   * typically a bugfix or improvement of the method
  * change all:
  *   * typically a new method

Each module installation must specify in a properties file the
version number range of input datasets it requires.
Each module installation must specify in a properties file the
exact version number of the output datasets it will produce upon
successfull execution.

===== Version Numbering Scheme =====
Our proposed version numbering scheme is derived from a widely
used source code version numbering standard with three digits. \\
A version number consists of three digits, separated each by a dot.
An example is **0.0.1** or **17.3.12**. Numbers are not prefixed by
zeros, so comparison must be done numerically not alphabetically.

The names of the three digits are: "major version"."minor version"."patch level"

===== Compatibility Levels Between Dataset Versions =====
We want to keep minor version number API compatibility. In detail:
  - different patch levels must produce identical results
  - different minor version numbers must produce compatible results
  - different major version numbers may produce incompatible results

===== Version Number Matching =====
Each of the three parts of the version number may be specified
using a regular expression. The following syntax should be supported:
  - the digits 0 to 9
  - the any-operator, star *. It matches any number.
  - the or-operator, vertical dash a|b. It combines two regular expressions a and b, and matches if a or b matches

===== Storing The Version Numbers Of Processed Modules =====

We need to track the version number of each module in the results storage,
so that results can be reproduced.

===== Examples =====
Note: The first example is discouraged for normal use, because this
example does not support newer patch levels of the same module.
Explicit versioning should only be used to reprocude previous results.
A workflow that can only use an exact version of ShadingCorrection:
<code>Version: 1.7.4</code>

Note: This is the most common example for typical normal use.
A workflow that can use any minor version and patch level of
Neighbor Tree Analysis:
<code>Version: 3.*.*</code>

Note: This is an example for modules that can support several
different API-incompatible input formats:
A workflow that can use several major versions and any minor
version and patch level of CellProfiler features:
<code>Version: 1|2|3|4.*.*</code>