aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2014-02-20 16:45:28 +0100
committerSiri Hansen <[email protected]>2014-03-28 15:19:49 +0100
commit8eb20d1fb0eb3a3b96d5e80e2e2617f893ef6986 (patch)
tree9c98ca35d3a5a9db93b84edbffb0cbe312d7b2c3
parent1ce93cb76672b523dbe2c9402f2d36ab431854ea (diff)
downloadotp-8eb20d1fb0eb3a3b96d5e80e2e2617f893ef6986.tar.gz
otp-8eb20d1fb0eb3a3b96d5e80e2e2617f893ef6986.tar.bz2
otp-8eb20d1fb0eb3a3b96d5e80e2e2617f893ef6986.zip
Add info about upgrade of core applications
In ref man for appup and in system documentation, design prinsiples, add a warning related to upgrade when version of erts, kernel, stdlib or sasl is changed. This will cause an emulator restart where new version of emulator and core applications will startup together with old versions of other applications. Care must be taken to avoid problems due to backwards incompatibility.
-rw-r--r--lib/sasl/doc/src/appup.xml23
-rw-r--r--system/doc/design_principles/release_handling.xml17
2 files changed, 35 insertions, 5 deletions
diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml
index 85fcbed3ba..95f315d269 100644
--- a/lib/sasl/doc/src/appup.xml
+++ b/lib/sasl/doc/src/appup.xml
@@ -4,7 +4,7 @@
<fileref>
<header>
<copyright>
- <year>1997</year><year>2013</year>
+ <year>1997</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -84,6 +84,9 @@
version identifier must be specified as a binary, e.g.</p>
<code type="none">&lt;&lt;"2\\.1\\.[0-9]+">></code>
<p>will match all versions <c>2.1.x</c>, where x is any number.</p>
+ <p>Note that the regular expression must match the complete
+ version string, so the above example will work for for
+ e.g. <c>2.1.1</c>, but not for <c>2.1.1.1</c></p>
</section>
<section>
@@ -339,7 +342,7 @@ restart_new_emulator
version of erts, kernel, stdlib and sasl are used when the
emulator restarts. Only one <c>restart_new_emulator</c>
instruction is allowed in the relup, and it shall be placed
- first. <seealso marker="systools#make_relup/3">systools:make_relup3,4</seealso>
+ first. <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso>
will ensure this when the relup is generated. The rest of the
relup script is executed after the restart as a part of the boot
script.</p>
@@ -347,11 +350,25 @@ restart_new_emulator
completed. To programatically find out if the upgrade is
complete,
call <seealso marker="release_handler#which_releases/0">
- release_handler:which_releases</seealso> and check if the
+ release_handler:which_releases/0,1</seealso> and check if the
expected release has status <c>current</c>.</p>
<p>The new release must still be made permanent after the upgrade
is completed. Otherwise, the old emulator is started in case of
an emulator restart.</p>
+ <warning>
+ <p>As stated above, the <c>restart_new_emulator</c>
+ instruction causes the emulator to be restarted with new
+ versions of <c>erts</c>, <c>kernel</c>, <c>stdlib</c> and
+ <c>sasl</c>. All other applications, however, will at startup
+ be running their old versions in this new emulator. In most
+ cases this is no problem, but every now and then there will be
+ incompatible changes to the core applications which may cause
+ trouble in this setting. Such incompatible changes (when
+ functions are removed) are normally preceded by a deprecation
+ over two major releases. To make sure your application is not
+ crashed by an incompatible change, always remove any call to
+ deprecated functions as soon as possible.</p>
+ </warning>
<pre>
restart_emulator
</pre>
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml
index 2a5831b89f..ba8a88d1c2 100644
--- a/system/doc/design_principles/release_handling.xml
+++ b/system/doc/design_principles/release_handling.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -329,13 +329,26 @@
automatically ensured.</p>
<p>When the release handler encounters the instruction, it first
generates a temporary boot file, which starts the new versions
- of the emulator and the core applications. Then it shuts down
+ of the emulator and the core applications, and the old version
+ of all other applications. Then it shuts down
the current emulator by calling <c>init:reboot()</c>, see
<c>init(3)</c>. All processes are terminated gracefully and
the system is rebooted by the heart program, using the
temporary boot file. After the reboot, the rest of the relup
instructions are executed. This is done as a part of the
temporary boot script.</p>
+ <warning>
+ <p>Since this mechanism causes the new versions of the
+ emulator and core applications to run with the old version of
+ other applications during startup, extra care must be taken to
+ avoid incompatibility. Incompatible changes in the core
+ applications may in some situations be necessary. If possible,
+ such changes are preceded by deprecation over two major
+ releases before the actual change. To make sure your
+ application is not crashed by an incompatible change, always
+ remove any call to deprecated functions as soon as
+ possible.</p>
+ </warning>
<p>An info report is written when the upgrade is completed. To
programatically find out if the upgrade is complete,
call <c>release_handler:which_releases(current)</c> and check