Release Procedures

This page details the various stages, processes and procedures required to create a release of RTEMS. RTEMS is the RTEMS Realtime kernel, tools, tests and documentation.

The RTEMS Project is a volunteer effort and only maintains the current and one previous release. Users wishing to have older releases maintained should enquire about commercial support. The RTEMS Project attempts to provide access to previous releases as release.

Release Terminology

• A release is the creation of any generated files and their packaging together with the source in a repository that makes the package available as a file.
• A release branch is a git branch pushed to the repositories.
• A release branch release is a git tag on a release branch with the tags pushed to the repositories.

Release Stages

The source code in the various git repositories will be in one of the following stages:

Stage	Description
MASTER_OPEN	The master branch in all repositories is open and new features and potentially unstable changes can be committed. Users should expect unstable behaviour.
MASTER_SLUSHY	The repositories are closed to new features. Features existing in the master branch can be completed. Users should expect unstable behaviour.
MASTER_FROZEN	The repositories are closed to all changes except bug fixes.
RELEASE_BRANCH	A release branch is made in each repository once all the repositories pass the required release test requirements. The master branch returns to the MASTER_OPEN stage. All changes must have a ticket and commits must reference the ticket. A release branch is tagged with each release as it is created. The release branch remains open until it is archived.
RELEASE_ARCHIVED	The release branch is archived. No further changes are made to the branch.

Stages changes on the master branch are announced on the devel@… mailing list. The decision to change is made by agreement of the core developers. There are no changes in the repositories to reflect this. The release page in the wiki will indicate the state.

Working on Releases

• Features for a master branch should be listed as an enhancement ticket.
• Only the current and previous release branches are active and all other release branches are archived.
• An archived release branch cannot be changed.

RTEMS Release Repositories

The following repositories are part of an RTEMS release:

1. RTEMS (​git://git.rtems.org/rtems.git)
2. RTEMS Source Builder (​git://git.rtems.org/rtems-source-builder.git)
3. RTEMS Tools (​git://git.rtems.org/rtems-tools.git)
4. RTEMS Documentation (​git://git.rtems.org/rtems-docs.git)
5. Example applications (​git://git.rtems.org/examples-v2.git)
6. Networking examples (​git://git.rtems.org/network-demos.git)

• The release branches and tags must be consistent across these repositories.

RTEMS Release Numbering and Naming

The RTEMS Release Number and Naming relates to all repositories and packages released. The version number has three (3) numbers and the numbers are major.minor.release.

Major

The major version number defines the release series. A release series up to RTEMS 4 has traditionally reflected changes in the user Application Programming Interface (API) and has been slow moving. RTEMS has shifted to support standards base interfaces for users and this means user API are stable and not changing. Therefore, RTEMS Series 5 and higher uses the major number to better reflect major feature changes in RTEMS.

Minor

The minor version number changes when a release branch is created.

Release

The release version number changes for a release branch release, that is, when a release is created on that release branch. The first release version number is 0. This is sometimes called the dot release.

RTEMS Branch Labels

The RTEMS release branches are labelled by the major release number and minor release delimited with a period (.). For example the release branch label for RTEMS 4.11 is 4.11.

A development release is any code taken from the master branch of a repository.

RTEMS Release 4 Series Numbering

Release numbering for the Series 4 releases use the minor release dot number of .99 for development releases. For example the development release numbering for RTEMS 4.11 is 4.11.99. This allows testing of any version number related code, processes and procedures to happen with correct minor version number.

The release procedure requires the release's minor dot number to be set to '0' before the release branch is created and it is used for the first branch release. Further branch releases increment the minor release number when a branch release is made.

RTEMS Release 5 Series And Higher Numbering

Release numbering for Series 5 and higher releases use even minor release numbers as development releases and odd minor release numbers for releases. For example RTEMS 5.0 is a development release, that is any code taken from the master branch, and RTEMS 5.1 is an actual RTEMS release. The minor release dot number stays at 0 for all development releases.

The release procedure requires the release's minor number is incremented to the next odd number then the release branch is created. The release minor dot number is incremented when a new release branch release is made.

---

Pre-Release Checklist

Must haves:

• Tools stabilized on known versions, these can be different versions if required. If it is not possible for a tool to be built it must be well documented in the release notes.
• All BSPs must build without error
• Select BSPs must run tests without errors:
  • sparc/erc32

Nice to haves:

• Warning reduction pass focusing on all SPARC BSPs, select PowerPC, ARM and MIPS.
• Coverage reports generated
  • sparc/erc32
• Review contents of top of each repo for being up to date.

---

Release Procedures

Start with either of the following two sets of instructions depending on whether creating a new Release Branch, or only a new Release Branch Release for an existing release branch. Follow these procedures for all of the Release Repositories.

Accompany either with announcements to the website, mailing lists, and social media.

Create a Release Branch for new Major or Minor

1. Create branch for release, for example git checkout -b 4.11
2. Follow the steps below for Create a Release Branch Release.
3. Switch back to master branch, git checkout master
4. Create a local branch for updating the development master, for example git checkout -b 5.0
5. Update master version numbers with release.sh in Bump (B) mode, for example ./release.sh -V 5.0.0 -M 5.0 -B.
6. Push to the master, for example git push upstream 5.0:master.
7. Bump default version to the current release, for example 5.0. (This may have been done already.)
8. Generate 'next' milestone

Create a Release Branch Release

1. Switch to Release Branch, for example git checkout 4.11.
2. Run release.sh in Dot (D) mode, for example ./release.sh -V 4.11.0 -M 4.11 -D.
3. Check changes for correctness.
4. Push Release Branch and Tags, for example git push upstream 4.11 and git push upstream --tags
5. Generate ChangeLog using script found in #2208
6. Upload files to FTP with sha256.
7. Update ​https://docs.rtems.org/
   1. Texinfo
   2. Doxygen
   3. RSB

Releasing Process

1. This procedure is run and tested on FreeBSD. It uses a large amount of bandwidth and so it typically run sync.rtems.org.
2. Documentation is built and this includes PDF there a valid documentation build environment is required including production quality fonts.

Clone the ​RTEMS Release repository and create the release providing the release's branch and the dot release number:

$ git clone git://git.rtems.org/rtems-release.git
$ cd rtems-release
$ ./rtems-release 4.11 0

NOTE: for a release candidate use 0-rc1 as the dot release number.