This page describes the release process used with MCUboot.
MCUboot uses semantic versioning, where version numbers follow a MAJOR.MINOR.PATCH format with the following guidelines on incrementing the numbers:
We add pre-release tags using the format MAJOR.MINOR.PATCH-rc1.
In the documentation, we mark an MCUBoot development version using the format MAJOR.MINOR.PATCH-dev.
Before making a release, update the docs/release-notes.md file to describe the release. This should be a high-level description of the changes, not a list of the git commits.
Provided that changes going into the release have followed the contribution guidelines, this should mostly consist of collecting the various snippets in the docs/release-notes.d directory. After incorporating these snippets into the release notes, the snippet files should be removed to ready the directory for the next release cycle.
Before each release, tags are made (see below) for at least one release candidate (a.b.c-rc1, followed by a.b.c-rc2 and the subsequent release candidates, followed by the official a.b.c release). The intent is to freeze the code and allow testing.
During the time between the rc1 and the final release, the only changes that should be merged into the main branch are those to fix bugs found in the RC and in the Mynewt metadata, as described in the next section.
imgtool is released through pypi.org (The Python package index). It requires its version to be updated by editing scripts/imgtool/__init__.py and modifying the exported version:
imgtool_version = "A.B.CrcN"
This version should match the current release number of MCUboot. The suffix rcN (with no dash) is accepted only for the pre-release versions under test, while numbers are accepted only for the final releases.
For more information, see this link.
On Mynewt, newt always fetches a versioned MCUboot release, so after the RC step is finished, the release needs to be exported by modifying repository.yml in the root directory; it must be updated with the new release version, including updates to the pseudo keys (*-(latest|dev)).
There is a version file used by Zephyr builds to indicate the version of MCUboot being used which needs to be updated at boot/zephyr/VERSION. For alignment with Zephyr versions, development versions should set PATCHLEVEL to 99 and EXTRAVERSION to dev, whilst production versions should correctly set PATCHLEVEL and clear EXTRAVERSION.
To make a release, make sure your local repo is on the tip version by fetching from origin. Typically, the releaser should create a branch named after the particular release.
Create a commit on top of the branch that modifies the version number in the top-level README.md, and create a commit, with just this change, with a commit text similar to "Bump to version a.b.c". Having the version bump helps to make the releases easier to find, as each release has a commit associated with it, and not just a tag pointing to another commit.
Once this is done, the release should create a signed tag with the appropriate tag name:
git tag -s va.b.c-rcn
The releaser will need to make sure that git is configured to use the proper signing key, and that the public key is signed by enough parties to be trusted.
At this point, the tag can be pushed to GitHub to make the actual release happen:
git push origin HEAD:refs/heads/main git push origin va.b.c-rcn
After the final (non-rc) a.b.0 release is made, a new branch must be created and pushed:
git checkout va.b.c git checkout -b va.b-branch git push origin va.b-branch
This branch will be used to generate new incremental PATCH releases for bug fixes or required minor updates (for example, new imgtool features).
Mark the MCUboot version as a development version.
The version number used should be specified for the next expected release. It should be larger than the last release version by incrementing the MAJOR or the MINOR number. It is not necessary to define the next version precisely as the next release version might still be different as it might be needed to do: