path: root/system/doc/system_principles/versions.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2014</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>Versions</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date>2014-02-19</date>
    <rev></rev>
    <file>versions.xml</file>
  </header>
    <section><title>OTP Version</title>
    <p>As of OTP release 17, the OTP release number corresponds to
    the major part of the OTP version. The OTP version as a concept was
    introduced in OTP 17. The <seealso marker="#version_scheme">version
    scheme</seealso> used is described in more detail below.</p>

    <p>OTP of a specific version is a set of applications of specific
    versions. The application versions identified by an OTP version
    corresponds to application versions that have been tested together
    by the Erlang/OTP team at Ericsson AB. An OTP system can however be
    put together with applications from different OTP versions. Such a
    combination of application versions has not been tested by the
    Erlang/OTP team. It is therefore <em>always preferred to use OTP
    applications from one single OTP version</em>.</p>

    <p>Release candidates have an <c>-rc&lt;N&gt;</c>
    suffix. The suffix <c>-rc0</c> will be used during development up to
    the first release candidate.</p>

    <section><title>Retrieving Current OTP Version</title>
    <p>In an OTP source code tree, the OTP version can be read from
    the text file <c>&lt;OTP source root&gt;/OTP_VERSION</c>. The
    absolute path to the file can be constructed by calling
    <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "OTP_VERSION"])</c>.</p>
    <p>In an installed OTP development system, the OTP version can be read
    from the text file <c>&lt;OTP installation root&gt;/releases/&lt;OTP release number&gt;/OTP_VERSION</c>.
    The absolute path to the file can by constructed by calling
    <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "releases", <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>, "OTP_VERSION"]).</c></p>
    <p>If the version read from the <c>OTP_VERSION</c> file in a
    development system has a <c>**</c> suffix, the system has been
    patched using the <c>otp_patch_apply</c> tool available to
    licensed customers. In this case, the system consists of application
    versions from multiple OTP versions. The version preceding the <c>**</c>
    suffix corresponds to the OTP version of the base system that
    has been patched. Note that if a development system is updated by
    other means than <c>otp_patch_apply</c>, the <c>OTP_VERSION</c> file
    may identify wrong OTP version.</p>

    <p>No <c>OTP_VERSION</c> file will be placed in a
    <seealso marker="create_target">target system</seealso> created
    by OTP tools. This since one easily can create a target system
    where it is hard to even determine the base OTP version. You may,
    however, place such a file there yourself if you know the OTP
    version.</p>
    </section>

    <section><title>OTP Versions Table</title>
    <p>The text file <c>&lt;OTP source root&gt;/otp_versions.table</c> that
    is part of the source code contains information about all OTP versions
    from OTP 17.0 up to current OTP version. Each line contains information
    about application versions that are part of a specific OTP version, and
    is on the format:</p>
<pre>
&lt;OtpVersion&gt; : &lt;ChangedAppVersions&gt; # &lt;UnchangedAppVersions&gt; :
</pre>
    <p><c>&lt;OtpVersion&gt;</c> is on the format <c>OTP-&lt;VSN&gt;</c>, i.e.,
    the same as the git tag used to identify the source.
    <c>&lt;ChangedAppVersions&gt;</c> and <c>&lt;UnchangedAppVersions&gt;</c>
    are space separated lists of application versions on the
    format <c>&lt;application&gt;-&lt;vsn&gt;</c>. 
    <c>&lt;ChangedAppVersions&gt;</c> corresponds to changed applications
    with new version numbers in this OTP version, and
    <c>&lt;UnchangedAppVersions&gt;</c> corresponds to unchanged application
    versions in this OTP version. Both of them might be empty, although
    not at the same time. If &lt;ChangedAppVersions&gt; is empty, no changes
    has been made that change the build result of any application. This could
    for example be a pure bug fix of the build system. The order of lines
    is undefined. All white space characters in this file are either space
    (character 32) or line-break (character 10).</p>
    <p>Using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one
    can easily find answers to various questions like:</p>
    <taglist>
      <tag>Which OTP versions are <c>kernel-3.0</c> part of?</tag>
      <item><p><c> $ grep ' kernel-3\.0 ' otp_versions.table</c></p></item>
      <tag>In which OTP version was <c>kernel-3.0</c> introduced?</tag>
      <item><p><c> $ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c></p></item>
    </taglist>
    <p>The above commands give a bit more information than the exact answers,
    but adequate information when manually searching for answers to these
    questions.</p>
    <warning><p>The format of the <c>otp_versions.table</c> might be subject
    to changes during the OTP 17 release.</p></warning>
    </section>
    </section>

    <section><title>Application Version</title>
    <p>As of OTP 17.0 application versions will use the same
    <seealso marker="#version_scheme">version scheme</seealso> as the
    OTP version. Application versions part of a release candidate will
    however not have an <c>-rc&lt;N&gt;</c> suffix as the OTP version.
    Also note that a major increment in an application version does not
    necessarily imply a major increment of the OTP version. This depends
    on whether the major change in the application is considered as a
    major change for OTP as a whole or not.</p>
    </section>

    <marker id="version_scheme"/>
    <section><title>Version Scheme</title>
    <note>Note that the version scheme was changed as of OTP 17.0. This implies
    that application versions used prior to OTP 17.0 do not adhere to this
    version scheme. <seealso marker="#otp_17_0_app_versions">A list of
    application versions used in OTP 17.0</seealso> can be found
    at the end of this document.</note>

    <p>In the normal case, a version will be constructed as
    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> where <c>&lt;Major&gt;</c>
    is the most significant part. However, more dot separated parts than
    this may exist. The dot separated parts consists of non-negative integers.
    If all parts less significant than <c>&lt;Minor&gt;</c> equals <c>0</c>,
    they are omitted. The three normal parts
    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> will be changed as
    follows:</p>
    <taglist>
      <tag><c>&lt;Major&gt;</c></tag><item>Increased when major changes,
      including incompatibilities, have been made.</item>
      <tag><c>&lt;Minor&gt;</c></tag><item>Increased when new functionality
      has been added.</item>
      <tag><c>&lt;Patch&gt;</c></tag><item>Increased when pure bug fixes
      have been made.</item>
    </taglist>
    <p>When a part in the version number is increased, all less significant
    parts are set to <c>0</c>.</p>

    <p>An application version or an OTP version identifies source code
    versions. That is, it does not imply anything about how the application
    or OTP has been built.</p>

    <section><title>Order of Versions</title>
    <p>Version numbers in general are only partially ordered. However,
    normal version numbers (with three parts) as of OTP 17.0 have a total
    or linear order. This applies both to normal OTP versions and
    normal application versions.</p>

    <p>When comparing two version numbers that have an order, one
    compare each part as ordinary integers from the most
    significant part towards less significant parts. The order is
    defined by the first parts of the same significance that
    differ. An OTP version with a larger version include all
    changes that that are part of a smaller OTP version. The same
    goes for application versions.</p>

    <p>In the general case, versions may have more than three parts. In
    this case the versions are only partially ordered. Note that such
    versions are only used in exceptional cases. When an extra
    part (out of the normal three parts) is added to a version number,
    a new branch of versions is made. The new branch has a linear
    order against the base version. However, versions on different
    branches have no order. Since they have no order, we
    only know that they all include what is included in their
    closest common ancestor. When branching multiple times from the
    same base version, <c>0</c> parts are added between the base
    version and the least significant <c>1</c> part until a unique
    version is found. Versions that have an order can be compared
    as described in the paragraph above.</p>

    <p>An example of branched versions: The version <c>6.0.2.1</c>
    is a branched version from the base version <c>6.0.2</c>.
    Versions on the form <c>6.0.2.&lt;X&gt;</c> can be compared
    with normal versions smaller than or equal to <c>6.0.2</c>,
    and other versions on the form <c>6.0.2.&lt;X&gt;</c>. The
    version <c>6.0.2.1</c> will include all changes in
    <c>6.0.2</c>. However, <c>6.0.3</c> will most likely
    <em>not</em> include all changes in <c>6.0.2.1</c> (note that
    these versions have no order). A second branched version from the base
    version <c>6.0.2</c> will be version <c>6.0.2.0.1</c>, and a
    third branched version will be <c>6.0.2.0.0.1</c>.</p>
    </section>
    </section>

    <marker id="otp_17_0_app_versions"/>
    <section><title>OTP 17.0 Application Versions</title>
    <p>The following application versions were part of OTP 17.0. If
    the normal part of an applications version number compares
    as smaller than the corresponding application version in this list,
    the version number does not adhere to the version scheme introduced
    in OTP 17.0 and should be considered as not having an order against
    versions used as of OTP 17.0.</p>
    <list>
      <item><c>asn1-3.0</c></item>
      <item><c>common_test-1.8</c></item>
      <item><c>compiler-5.0</c></item>
      <item><c>cosEvent-2.1.15</c></item>
      <item><c>cosEventDomain-1.1.14</c></item>
      <item><c>cosFileTransfer-1.1.16</c></item>
      <item><c>cosNotification-1.1.21</c></item>
      <item><c>cosProperty-1.1.17</c></item>
      <item><c>cosTime-1.1.14</c></item>
      <item><c>cosTransactions-1.2.14</c></item>
      <item><c>crypto-3.3</c></item>
      <item><c>debugger-4.0</c></item>
      <item><c>dialyzer-2.7</c></item>
      <item><c>diameter-1.6</c></item>
      <item><c>edoc-0.7.13</c></item>
      <item><c>eldap-1.0.3</c></item>
      <item><c>erl_docgen-0.3.5</c></item>
      <item><c>erl_interface-3.7.16</c></item>
      <item><c>erts-6.0</c></item>
      <item><c>et-1.5</c></item>
      <item><c>eunit-2.2.7</c></item>
      <item><c>gs-1.5.16</c></item>
      <item><c>hipe-3.10.3</c></item>
      <item><c>ic-4.3.5</c></item>
      <item><c>inets-5.10</c></item>
      <item><c>jinterface-1.5.9</c></item>
      <item><c>kernel-3.0</c></item>
      <item><c>megaco-3.17.1</c></item>
      <item><c>mnesia-4.12</c></item>
      <item><c>observer-2.0</c></item>
      <item><c>odbc-2.10.20</c></item>
      <item><c>orber-3.6.27</c></item>
      <item><c>os_mon-2.2.15</c></item>
      <item><c>ose-1.0</c></item>
      <item><c>otp_mibs-1.0.9</c></item>
      <item><c>parsetools-2.0.11</c></item>
      <item><c>percept-0.8.9</c></item>
      <item><c>public_key-0.22</c></item>
      <item><c>reltool-0.6.5</c></item>
      <item><c>runtime_tools-1.8.14</c></item>
      <item><c>sasl-2.4</c></item>
      <item><c>snmp-4.25.1</c></item>
      <item><c>ssh-3.0.1</c></item>
      <item><c>ssl-5.3.4</c></item>
      <item><c>stdlib-2.0</c></item>
      <item><c>syntax_tools-1.6.14</c></item>
      <item><c>test_server-3.7</c></item>
      <item><c>tools-2.6.14</c></item>
      <item><c>typer-0.9.6</c></item>
      <item><c>webtool-0.8.10</c></item>
      <item><c>wx-1.2</c></item>
      <item><c>xmerl-1.3.7</c></item>
    </list>
    </section>
</chapter>