aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/system_principles/versions.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/system_principles/versions.xml')
-rw-r--r--system/doc/system_principles/versions.xml290
1 files changed, 148 insertions, 142 deletions
diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml
index ed6fd1f7fe..a0f13774ce 100644
--- a/system/doc/system_principles/versions.xml
+++ b/system/doc/system_principles/versions.xml
@@ -31,94 +31,100 @@
<rev></rev>
<file>versions.xml</file>
</header>
- <section><title>OTP Version</title>
+ <marker id="versions section"></marker>
+
+ <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>
-
+ introduced in OTP 17. The version scheme used is described in detail in
+ <seealso marker="#version_scheme">Version Scheme</seealso>.</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
+ 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
+ suffix. The suffix <c>-rc0</c> is 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
- <seealso marker="../installation_guide/OTP-PATCH-APPLY"><c>otp_patch_apply</c></seealso>
- tool. 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 an incorrect 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>
+ <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
+ <seealso marker="../installation_guide/OTP-PATCH-APPLY"><c>otp_patch_apply</c></seealso>
+ tool. 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. Notice that if a development system is updated by
+ other means than <c>otp_patch_apply</c>, the file <c>OTP_VERSION</c>
+ can identify an incorrect OTP version.</p>
+ <p>No <c>OTP_VERSION</c> file is 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 can,
+ however, place such a file there 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>
+ <title>OTP Versions Table</title>
+ <p>The text file <c>&lt;OTP source root&gt;/otp_versions.table</c>,
+ which is part of the source code, contains information about all
+ OTP versions from OTP 17.0 up to the current OTP version. Each line
+ contains information about application versions that are part of a
+ specific OTP version, and has the following format:</p>
+ <pre>
+&lt;OtpVersion&gt; : &lt;ChangedAppVersions&gt; # &lt;UnchangedAppVersions&gt; :</pre>
+ <p><c>&lt;OtpVersion&gt;</c> has the format <c>OTP-&lt;VSN&gt;</c>,
+ that is, the same as the git tag used to identify the source.</p>
+ <p><c>&lt;ChangedAppVersions&gt;</c> and
+ <c>&lt;UnchangedAppVersions&gt;</c> are space-separated lists of
+ application versions and has the format
+ <c>&lt;application&gt;-&lt;vsn&gt;</c>.</p>
+ <list type="bulleted">
+ <item><c>&lt;ChangedAppVersions&gt;</c> corresponds to changed
+ applications with new version numbers in this OTP version.</item>
+ <item><c>&lt;UnchangedAppVersions&gt;</c> corresponds to unchanged
+ application versions in this OTP version.</item>
+ </list>
+ <p>Both of them can be empty, but not at the same time.
+ If <c>&lt;ChangedAppVersions&gt;</c> is empty, no changes have
+ 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>By using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one
+ can easily find answers to various questions like:</p>
+ <list type="bulleted">
+ <item><p>Which OTP versions are <c>kernel-3.0</c> part of?</p>
+ <p><c>$ grep ' kernel-3\.0 ' otp_versions.table</c> </p></item>
+ <item><p>In which OTP version was <c>kernel-3.0</c> introduced?</p>
+ <p><c>$ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c>
+ </p></item>
+ </list>
+ <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
+ <section>
+ <title>Application Version</title>
+ <p>As of OTP 17.0 application versions 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.
@@ -126,88 +132,88 @@
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>
+ </section>
+ <section>
+ <title>Version Scheme</title>
<marker id="version_scheme"/>
- <section><title>Version Scheme</title>
- <note>Note that the version scheme was changed as of OTP 17.0. This implies
+ <note><p>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
+ application versions used in OTP 17.0</seealso> is included at the
+ end of this section</p></note>
+ <p>In the normal case, a version is constructed as
+ <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c>,
+ where <c>&lt;Major&gt;</c> is the most significant part.</p>
+ <p>However, more dot-separated parts than this can exist.
+ The dot-separated parts consist 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> are 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
+ <list type="bulleted">
+ <item><c>&lt;Major&gt;</c> - Increases when major changes,
+ including incompatibilities, are made.</item>
+ <item><c>&lt;Minor&gt;</c> - Increases when new
+ functionality is added.</item>
+ <item><c>&lt;Patch&gt;</c> - Increases when pure bug fixes
+ are made.</item>
+ </list>
+ <p>When a part in the version number increases, 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
+ versions. That is, it implies nothing 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>
+ <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 to less significant parts. The order is
+ defined by the first parts of the same significance that
+ differ. An OTP version with a larger version includes all
+ changes that are part of a smaller OTP version. The same
+ goes for application versions.</p>
+ <p>In general, versions can have more than three parts.
+ The versions are then only partially ordered. 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, and therefore one can only conclude
+ 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 previous paragraph.</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>
+ <section>
+ <title>OTP 17.0 Application Versions</title>
<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,
+ <p>The following list details the application versions that
+ were part of OTP 17.0. If
+ the normal part of an application version number compares
+ as smaller than the corresponding application version in the 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
+ in OTP 17.0 and is to be considered as not having an order against
versions used as of OTP 17.0.</p>
<list>
<item><c>asn1-3.0</c></item>
@@ -263,6 +269,6 @@
<item><c>wx-1.2</c></item>
<item><c>xmerl-1.3.7</c></item>
</list>
- </section>
+ </section>
</chapter>