From 9f9c9b19d3bdf9d2d0c054beb8ab31460c487523 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 24 May 2018 16:05:38 +0200 Subject: Info about support, compatibility, deprecation and removal --- system/doc/system_principles/misc.xml | 198 ++++++++++++++++++++++++++++++ system/doc/system_principles/part.xml | 1 + system/doc/system_principles/versions.xml | 39 +++++- system/doc/system_principles/xmlfiles.mk | 3 +- 4 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 system/doc/system_principles/misc.xml diff --git a/system/doc/system_principles/misc.xml b/system/doc/system_principles/misc.xml new file mode 100644 index 0000000000..dd6c2a1336 --- /dev/null +++ b/system/doc/system_principles/misc.xml @@ -0,0 +1,198 @@ + + + + +
+ + 2018 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + Support, Compatibility, Deprecations, and Removal + + + + + + 2018-05-21 + + misc.xml +
+ +
+ + Supported Releases +

+ In general, bugs are only fixed on the latest + release, + and new features are introduced in the upcoming release that is + under development. However, when we, due to internal reasons, fix + bugs on older releases, these will be available and announced as well. +

+

+ Due to the above, pull requests are only accepted on the + maint and the master branches in our + git repository. + The maint branch contains changes planned for the next + maintenance patch package + on the latest OTP release and the master branch contain + changes planned for the upcoming OTP release. +

+
+ +
+ + Compatibility +

+ We always strive to remain as compatible as possible + even in the cases where we give no compatibility guarantees. +

+

+ Different parts of the system will be handled differently + regarding compatibility. The following items describe how + different parts of the system are handled. +

+ + Erlang Distribution + +

+ Erlang nodes can communicate across at least + two preceding and two subsequent releases. +

+ + Compiled BEAM Code, NIF Libraries and Drivers + +

+ Compiled code can be loaded on at least two + subsequent releases. +

+

+ Loading on previous releases is not supported. +

+ + Compiled HiPE Code + +

+ Compiled HiPE code can be loaded on the exact same build + of ERTS that was used when compiling the code. It might + however work on other builds, the emulator verifies + checksums in order to determine if it can load the code + or not. Note that HiPE has some limitations. For more + information see the documentation of the + HiPE application. +

+ + APIs + +

Compatible between releases.

+ + Compiler Warnings + +

New warnings may be issued between releases.

+ + Command Line Arguments + +

Incompatible changes may occur between releases.

+ + OTP Build Procedures +

Incompatible changes may occur between releases.

 + +

+ Under certain circumstances incompatible changes might be + introduced even in parts of the system that should be compatible + between releases. Things that might trigger incompatible changes + like this are: +

+ + Security Issues + +

+ It might be necessary to introduce incompatible changes + in order to solve a security issue. This kind of + incompatibility might occur in a patch. +

+ + Bug Fixes + +

+ We will not be bug-compatible. A bug fix might introduce + incompatible changes. This kind of incompatibility + might occur in a patch. +

+ + Severe Previous Design Issues + +

+ Some parts of OTP were designed a very long time ago and + did not necessarily take today's computing environments into + account. In some cases the consequences of those design + decisions are too severe. This may be performance wise, + scalability wise, etc. If we deem the consequences too + severe, we might introduce incompatible changes. This kind + of incompatibility will not be introduced in a patch, but + instead in the next release. +

+ + +

+ Peripheral, trace, and debug functionality is at greater + risk of being changed in an incompatible way than functionality + in the language itself and core libraries used during operation. +

+
+ +
+ + Deprecation +

+ Functionality is deprecated when new functionality is + introduced that is preferred to be used instead of the + old functionality that is being deprecated. The deprecation + does not imply removal of the functionality unless + an upcoming removal is explicitly stated in the deprecation. +

+

+ Deprecated functionality will be documented as deprecated, and + compiler warnings will be issued, when appropriate, as + early as possible. That is, the new preferred functionality + will appear at the same time as the deprecation is issued. + A new deprecation will at least be announced in a release + note and the documentation. +

+
+ +
+ + Removal +

+ Legacy solutions may eventually need to be removed. In such + cases, they will be phased out on a long enough time period + to give users the time to adapt. Before removal of + functionality it will be deprecated at least during one + release with an explicit announcement about + the upcoming removal. A new deprecation will at least be + announced in a release note and the documentation. +

+

+ Peripheral, trace, and debug functionality is at greater + risk of removal than functionality in the language itself + and core libraries used during operation. +

+
+ + + diff --git a/system/doc/system_principles/part.xml b/system/doc/system_principles/part.xml index 1b87ecd350..9f70f40dfb 100644 --- a/system/doc/system_principles/part.xml +++ b/system/doc/system_principles/part.xml @@ -34,4 +34,5 @@ + diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml index b9f7fa4bf6..355c8fd2d5 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -32,9 +32,9 @@ versions.xml -
+ OTP Version

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 @@ -136,8 +136,8 @@

- Version Scheme + Version Scheme

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. A list of @@ -207,8 +207,41 @@

- OTP 17.0 Application Versions + + Releases and Patches +

+ When a new OTP release is released it will have an OTP + version on the form <Major>.0 where the + major OTP version number equals the release number. + The major version number is increased one step since the + last major version. All other OTP versions with the same + major OTP version number are patches on that OTP release. +

+

+ Patches are either released as maintenance patch packages + or emergency patch packages. The only difference is that + maintenance patch packages are planned and usually contain + more changes than emergency patch packages. Emergency patch + packages are released to solve one or more specific issues + when such are discovered. +

+

+ The release of a maintenance patch package usually imply + an increase of the OTP <Minor> version while + the release of an emergency patch package usually imply an + increase of the OTP <Patch> version. This is + however not necessarily always the case since changes of + OTP versions are based on the actual changes in the code + and not based on whether the patch was planned or not. + For more information see the + Version Scheme + section above. +

+
+ +
+ OTP 17.0 Application Versions

The following list details the application versions that were part of OTP 17.0. If the normal part of an application version number compares diff --git a/system/doc/system_principles/xmlfiles.mk b/system/doc/system_principles/xmlfiles.mk index 77d6747414..353c2c7f7f 100644 --- a/system/doc/system_principles/xmlfiles.mk +++ b/system/doc/system_principles/xmlfiles.mk @@ -21,7 +21,8 @@ SYSTEM_PRINCIPLES_CHAPTER_FILES = \ system_principles.xml \ error_logging.xml \ upgrade.xml \ - versions.xml + versions.xml \ + misc.xml SYSTEM_PRINCIPLES_CHAPTER_GEN_FILES = \ create_target.xml -- cgit v1.2.3