= Release Procedures

[[TOC(Developer/Release, depth=4)]]

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 [mailto:devel@rtems.org devel@rtems.org] 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 ([https://git.rtems.org/rtems.git git://git.rtems.org/rtems.git])
1. RTEMS Source Builder ([https://git.rtems.org/rtems-source-builder.git git://git.rtems.org/rtems-source-builder.git])
1. RTEMS Tools ([https://git.rtems.org/rtems-tools.git git://git.rtems.org/rtems-tools.git])
1. RTEMS Documentation ([https://git.rtems.org/rtems-docs.git git://git.rtems.org/rtems-docs.git])
1. Example applications ([https://git.rtems.org/examples-v2.git git://git.rtems.org/examples-v2.git])
1. Networking examples ([https://git.rtems.org/network-demos.git 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

The release numbering scheme changed with RTEMS 5. The master branch has the version N.0.0 with N being the next major release number. The first release of this series will have the version number N.1.0. There will be 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. Tools will use N as the version number and must work with all releases and the release branch of the N series.

Examples:
* 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

----
= Release Procedures =

The following are the release procedures used to manage version number updates, creating a release branch and cutting a releasing.

== Release Numbering ==

The follow procedures are use to update the revision numbers:

=== RTEMS Source Builder ===

  ||= TDB =||

=== RTEMS Tools ===

  ||= TDB =||

=== RTEMS Kernel ===

Update the following files in the RTEMS Kernel repository:

  || `aclocal/version.m4` ||
  || `c/src/aclocal/version.m4` ||
  || `cpukit/aclocal/version.m4` ||
  || `testsuites/aclocal/version.m4` ||

=== RTEMS LibBSD ===

  ||= TDB =||

=== RTEMS Examples ===

  ||= TDB =||

=== RTEMS Documentation ===

  ||= TDB =||

=== RTEMS Home Website ===

 TDB

=== RTEMS Wiki ===

 TDB

----
chrisj; I will move the content below to above when releasing.
----
 
= 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 [#RTEMSReleaseRepositories 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`
 1. Follow the steps below for Create a Release Branch Release.
 1. Switch back to master branch, `git checkout master`
 1. Create a local branch for updating the development master, for example `git checkout -b 5.0`
 1. Update master version numbers with release.sh in Bump (B) mode, for example `./release.sh -V 5.0.0 -M 5.0 -B`.
 1. Push to the master, for example `git push upstream 5.0:master`.
 1. Bump default version to the current release, for example 5.0. (This may have been done already.)
 1. Generate 'next' milestone

== Create a Release Branch Release ==

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


== Release Procedure ==

The following documents the release procedure use to release RTEMS. The various stages are documented and then an example session to create a release is documented.

=== Version Numbering ===

The RTEMS Repository `rtems.git` contains a version number in a number of M4 files used by the `autoconf` build system. The release branch it kept at the development version number, for example for 4.11 it is `4.10.99`. Only the build release tar files have this changed to the exact release. This avoids someone using a git version of the branch and getting a valid release version number.

=== Building A Release ===

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

Clone the [https://git.rtems.org/rtems-release/ 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.

The release directory tree `4.11.0` is created. This can be copied to the RTEMS FTP server.

=== Repository Tagging ===

After a release is built we need to tag the repositories.

The tag is the release label. We only tag repositories with real releases, we do not tag release candidates.

The following repositories need to be tagged:

1. ssh://user@dispatch.rtems.org:/data/git/rtems-release.git
1. ssh://user@dispatch.rtems.org:/data/git/rtems-source-builder.git
1. ssh://user@dispatch.rtems.org:/data/git/rtems-tools.git
1. ssh://user@dispatch.rtems.org:/data/git/rtems.git
1. ssh://user@dispatch.rtems.org:/data/git/rtems-docs.git
1. ssh://user@dispatch.rtems.org:/data/git/rtems-libbsd.git
1. ssh://user@dispatch.rtems.org:/data/git/examples-v2.git

To tag a remote git repository do:

{{{
$ git tag 4.11.0 4.11
$ git push origin 4.11.0
}}}

The user tagging the repositories need to ensure their keys are suitably set up.

The `rtems-release.git` repository does not have branches, it is continuous line that is tagged for each release. To tag it use:

{{{
$ git tag 4.11.0 master
}}}

=== Release Session ===

{{{
$ git ssh://user@dispatch.rtems.org/data/git/rtems-release.git rtems-release.git
$ cd rtems-release.git
$ ./rtems-release 4.11 1
$ scp -r 4.11.1 user@dispatch.rtems.org:/data/ftp/pub/rtems/release/4.11/.
$ ./rtems-release-tag user 4.11 1
}}}