start/user: describe version numbers and releases

Closes #2562.

1 files changed, 49 insertions, 0 deletions

diff --git a/user/start/preparation.rst b/user/start/preparation.rst
index 546a03d..eb0d56b 100644
--- a/user/start/preparation.rst
+++ b/user/start/preparation.rst
@@ -1,8 +1,10 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2018 Shashvat Jain
 .. Copyright (C) 2019 embedded brains GmbH
 .. Copyright (C) 2019 Sebastian Huber
 .. Copyright (C) 2020 Chris Johns
+.. Copyright (C) 2020 Gedare Bloom
 
 .. _QuickStartPreparation:
 
@@ -62,3 +64,50 @@ If you are looking for a hardware target to run RTEMS on we recommend the
 BSP. The BeagleBone Black support includes the RTEMS BSD Library (``libbsd``)
 and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool
 suite name is ``arm-rtems5``.
+
+Selecting a Version of RTEMS
+----------------------------
+
+In the examples of this manual we will often refer to a specific version of
+RTEMS, which will usually be the version that accompanied the publication of
+this documentation manual. That may not be the appropriate version for you to
+use, for example, it may be too old (or too new) depending on what you are
+trying to do.  If you're not sure what version to use, we generally recommend
+using the most recent release or the development head (master), and you may
+want to consult with the same version of the documentation. We hope that newer
+is better.
+
+An RTEMS *release* involves the creation of a single downloadable file,
+normally a compressed tarball, that packages the source of all the repositories
+in a state consistent with the time the release is created.
+A release branch is a git branch pushed to the repositories named with the
+numeric identifier of the branch.
+A release branch release is a git tag on a release branch with
+the tags pushed to the repositories.
+
+Numbering for RTEMS versions beginning with RTEMS 5 uses a format as follows.
+The master branch has the version **N.0.0** with N being the next major release
+number. The first release of this series has the version number **N.1.0.** and
+there is exactly one commit with this version number in the corresponding
+repository. The first bugfix release (minor release) of this series will have
+the version number **N.2.0**. The release branch will have the version
+number **N.M.1** with **M** being the last minor release of this series.
+
+For example:
++ 5.0.0 is the version number of the development master for the 5 series.
++ 5.1.0 is the first release of the 5 series.
++ 5.1.1 is the version number of the 5 series release branch right after
+  the 5.1.0 release until 5.2.0 is released.
++ 5.2.0 is the first bugfix release of the 5 series
++ 5.2.1 is the version number of the 5 series release branch right after
+  the 5.2.0 release until 5.3.0 is released.
++ 6.0.0 is the version number of the development master for the 6 series.
+
+RTEMS development tools use **N** as the version number and are expected to
+work with all releases and the release branch of the N series.
+So to build tools for compiling RTEMS version number 5.1.0 for SPARC use
+``sparc-rtems5``. Despite the number not increasing, the tools may change
+within a release branch, for example the tools packaged with 5.1.1 still use
+the ``sparc-rtems5`` moniker, but are likely not the same as the tools used
+in version 5.1.0. This tool mismatch can be a source of confusion. Be sure to
+use the toolchain that matches your release.