Skip to content

[draft] Managing a Release

Martine Lenders edited this page Apr 30, 2019 · 25 revisions


  1. Checklist
  2. Preparation
  3. Feature Freeze and Testing
  4. Actual Release
  5. Applications Repository
  6. Resources
  7. Email templates

1. Checklist


  • Read “Managing a release” wiki
  • Gather improvements and tips from previous release manager
  • Decide and announce feature freeze dates
  • Create milestone label, and label PRs that have been already merged
  • Gather features to push from contributors, and apply milestone label
  • Familiarise with release specs and tests, incl open issues and PRs

Soft feature freeze

  • Send soft feature freeze email
  • Familiarise with nearly-merged, high impact PRs, and contact the contributors to ask them to hold

Hard Feature Freeze

Do the below actions iteratively, generating new release candidates, until all release specs tests pass.

  • Generate branch and tag for release candidate
  • Open issue in release specs repo for release candidate
  • Send hard feature freeze email
  • Co-ordinate testing for release candidate
  • Co-ordinate bugfixing for release candidate on master
  • Backport bugfixes for release candidate to release branch


  • Create a GPG key and upload it to GitHub
  • Generate etherpad with list of new features and known issues, and share
  • Finalise etherpad and PR it onto release-notes.txt (incl backporting)
  • Update release statistics wiki
  • Create a VERSION file and raise PR against the release branch
  • Release either manually or using the release manager script
  • Inform all lists about the release

2. Preparation

A good time to start preparing for the release is two months before the intended release date. Keep track of open pull requests and issues, especially of those marked with the Milestone label for the imminent release. This is a good time to clean up the GitHub repository and get rid of outdated, redundant or already fixed pull requests and issues.

Get in contact with the maintainers, discuss ongoing development and generate a short and realistic list of wanted features which should be published to the maintainers mailing list, on agreement. It is worth it to ask around for planned holidays to estimate an appropriate timetable. You should announce a date for the feature freeze and the estimated release date on all mailing lists.

During the month of release you should keep track of the development progress, coordinate between pull requests and help to get candidates merged. Shortly before feature freeze you should postpone pull requests that will (obviously) not make it until feature freeze. This SHOULD NOT be commented.

3. Feature Freeze and Testing

There are two feature freezes: soft and hard.

Soft feature freeze is the date after which “high impact” PRs cannot be merged. What defines “high impact” is at the release manager’s discretion, but typically in the past this has meant large structural changes to common code or API changes to common code, with “common” meaning shared between the majority of boards and application scenarios.

Hard feature freeze is the date at which the release branch gets created. When hard feature freeze emerges there should be at most bugfix pull requests open with a label for this release. Ideally but not mandatorily, these get merged before the first release candidate goes out. Only bugfixes to address release specification test failures can be merged into the release branch after this date. Any PRs can be merged into RIOT master after this date.

Any bugfixes should be merged into RIOT master and backported into the release branch by creating an identical PR against it. The backport_pr tool in the RIOT repo can be used to do this automatically. To co-ordinate testing, you can use the checkboxes and the discussion in the release candidate's issue, and/or the release tracking spreadsheet, at your discretion.mOnce all bugfixes addressing test failures have been merged and backported, a new release candidate is generated and testing begins again. This happens iteratively until we get a release candidate which passes all the tests without any further bugfixes. As there are "always" known issues, and deadlines need to be satisfied, it is possible to abstain at some point from backporting and re-testing iteratively, and list the issue as known in the release notes.

Automatic freezing and release candidate generation

Feature freeze:

riot-release-manager feature-freeze

Generating a new release candidate:

riot-release-manager rc

Manual freezing and release candidate generation

Even if you're using the release manager script, it's worth reading this section so you know what's going on.

Generate the release branch and git tags in the following way:

  • Clone the RIOT repository via ssh: git clone
  • Create a annotated tag that acts as starting point for the next release and a reference point for the RIOT_VERSION macro in master: git tag -m "Development branch towards release" <> where the date should be the date of the next release
  • And push this tag via git push origin <>
  • Checkout a new branch: git checkout -b <> where the date should be the date of the *current release
  • Push this branch to remote: git push origin <>:<> (Please note that you need a PubKey assigned to your account and obviously you need to be a RIOT maintainer)
  • Configure the branch protection of that branch on GitHub at (replace with proper release); the following configuration should suffice (note the push rights for Maintainers so you can push the final release commit later!): RIOT release branch configuration Note also: even if other status checks or CI servers are activated, only Murdock needs to be activated for required checking
  • Next, create a (lightweight; so no -a parameter, otherwise the version string in master will point to this tag!) tag for the first release candidate: git tag <>
  • And push this tag via git push origin <>

In the RIOT Release Specs repository create a new issue containing checkboxes for all release tests (have a look at closed issues from previous releases). A pointer to the release candidate and the issue for tracking testing efforts should be sent to the mailing lists with a request for help.

When generating a new release candidate, the release candidate needs to be tagged, a new issue needs to be created in the Release Specs repository and testing starts from the beginning (as described above).

4. Actual Release

Once a release candidate passed all tests you are ready to create the release notes. Open an etherpad and list new features, major improvements and features as well as known issues as done in previous releases. Make sure the line length is about 90 characters. You should share this pad with other maintainers and give them some time for review. Alternatively you can open a pull request with your notes and discuss there. But the former has proven well so far.

Now the notes need to go into the release-notes archive and must be appended on RIOT master as well as on the release branch. Both can be done via pull requests. The list of contributors can be deduced from git shortlog --no-merges -n -s OLD_RELEASE..RELEASE_BRANCH | cut -f 2 | sort after removing duplicates.

Create a VERSION file in the base of the repository with the release version with the following content and do a PR on the release branch.


We maintain a Release statistic where you should add numbers from the previously created release. To get these numbers in a formatted way, simply execute ./dist/tools/release-stats/ <old><new> and copy paste the outcome to the table on our Release statistics wiki page.

After you have released, be sure to inform all RIOTers about the release via mail on all lists.

Automatic releasing

Run the command

riot-release-manager release

Manual releasing

Again, it's worth reading this section even if you're using the release manager tool.

Tag this release as you did for the release candidate, except that you should sign it (git tag -s Only tag it this time. Additionally, to assure our users that the release wasn't messed with by third parties it also needs to be signed with GPG. You might also need to configure your gpg.program if you are using any other command for GPG than gpg (e.g. gpg2 on newer Ubuntu versions). For the signature to be visible in GitHub it is advised that you also upload your GPG public key to GitHub.

Now that everything is ready, create the release. This can easily be done via GitHubs web interface. In the RIOT repository click on Releases->Draft a new release. Assign the tag you previously created and signed, set title `RIOT- and paste the release notes below. Et voilà, that's the release.

5. Other repositories

Don't forget to update the submodule in the applications repository and Tutorials repository and test if the applications still work.

6. Resources

Description Location
Release spec test repository
Release manager tool
Test automation helper scripts
Pending changes to test automation helper scripts
Backport automation script {RIOTBASE}/dist/tools/backport_pr
Release statistics wiki
Release stats script {RIOTBASE}/dist/tools/release-stats
Release management org spreadsheet
Release test tracking spreadsheet

7. Email templates

These templates are suggestions, if useful. Whatever the phrasing, emails with similar content should be sent out to all mailing lists at various stages of the release process.

Date announcement and feature request

Release [YYYY.MM] - dates and feature requests


Dear RIOTers,

The release dates for the upcoming release cycle are fixed as follows:

- [Date] - soft feature freeze, for high impact features

- [Date] - hard feature freeze, for all features

- [Date] - Release date

Could you please send your suggestions for features which you would like to see merged during this release cycle.

Best regards, and happy hacking!


Soft feature freeze announcement

Release [YYYY.MM] - Soft feature freeze now effective


Dear RIOTers,

The soft feature freeze (for high impact PRs) is now effective.

As a gentle reminder: the final feature freeze (for all PRs) is April 5th.

Wishing you a happy code/polish/review/merge sprint,

Hard feature freeze announcement

Release [YYYY.MM] - Hard feature freeze now effective


Dear RIOTers,

We've created the [YYYY.MM] release branch, so we are now officially in
feature freeze. This means from now only bugfixes will be backported to
the `[YYYY.MM]-branch`. If anyone has any bugfixes or documentation
improvements that they feel should be part of this release please let me know.

New features can still be merged into master during this period.

The tracking issue of Release candidate 1 [1] is opened. If you want to help
with testing, please put your name against the corresponding item in the
linked spreadsheet.

Thanks all for the awesome work!

Best regards,



Release announcement

Release [YYYY.MM]


Dear RIOTers,

we are happy to announce the [XX]th official release of RIOT:

----------------------- * RIOT [YYYY.MM] * -----------------------

[Paste the “about the release” text here]

You can download the RIOT release from Github by cloning the repository
and checkout the release tag [1] or by downloading the tarball [2], and
look up the release notes for further details [3].

A big thank you to everybody who contributed!

Best regards,



Clone this wiki locally
You can’t perform that action at this time.