1# Release process 2 3This page describes the release process used with MCUboot. 4 5## Version numbering 6 7MCUboot uses [semantic versioning][semver], where version numbers 8follow a `MAJOR.MINOR.PATCH` format with the following guidelines on 9incrementing the numbers: 10 111. MAJOR version when there are incompatible API changes. 122. MINOR version when new functionalities were added in a 13 backward-compatible manner. 143. PATCH version when there are backward-compatible bug fixes. 15 16We add pre-release tags using the format `MAJOR.MINOR.PATCH-rc1`. 17 18In the documentation, we mark an MCUBoot development version using the 19format `MAJOR.MINOR.PATCH-dev`. 20 21## Release notes 22 23Before making a release, update the `docs/release-notes.md` file 24to describe the release. This should be a high-level description of 25the changes, not a list of the git commits. 26 27Provided that changes going into the release have followed the 28contribution guidelines, this should mostly consist of collecting the 29various snippets in the `docs/release-notes.d` directory. After 30incorporating these snippets into the release notes, the snippet files 31should be removed to ready the directory for the next release cycle. 32 33## Release candidates 34 35Before each release, tags are made (see below) for at least one 36release candidate (a.b.c-rc1, followed by a.b.c-rc2 and the subsequent 37release candidates, followed by the official a.b.c release). The intent 38is to freeze the code and allow testing. 39 40During the time between the rc1 and the final release, the only changes 41that should be merged into the main branch are those to fix bugs found 42in the RC and in the Mynewt metadata, as described in the next section. 43 44## Imgtool release 45 46imgtool is released through pypi.org (The Python package index). 47It requires its version to be updated by editing 48`scripts/imgtool/__init__.py` and modifying the exported version: 49``` 50imgtool_version = "A.B.CrcN" 51``` 52 53This version should match the current release number of MCUboot. The 54suffix `rcN` (with no dash) is accepted only for the pre-release versions 55under test, while numbers are accepted only for the final releases. 56 57For more information, see [this 58link](https://www.python.org/dev/peps/pep-0440/#pre-releases). 59 60## Mynewt release information 61 62On Mynewt, `newt` always fetches a versioned MCUboot release, so after 63the RC step is finished, the release needs to be exported by modifying 64`repository.yml` in the root directory; it must be updated with the 65new release version, including updates to the pseudo keys 66(`*-(latest|dev)`). 67 68## Zephyr release information 69 70There is a version file used by Zephyr builds to indicate the version 71of MCUboot being used which needs to be updated at 72`boot/zephyr/VERSION`. For alignment with Zephyr versions, development 73versions should set `PATCHLEVEL` to `99` and `EXTRAVERSION` to `dev`, 74whilst production versions should correctly set `PATCHLEVEL` and clear 75`EXTRAVERSION`. 76 77## Tagging and release 78 79To make a release, make sure your local repo is on the tip version by 80fetching from origin. Typically, the releaser should create a branch 81named after the particular release. 82 83Create a commit on top of the branch that modifies the version number 84in the top-level `README.md`, and create a commit, with just this 85change, with a commit text similar to "Bump to version a.b.c". 86Having the version bump helps to make the releases 87easier to find, as each release has a commit associated with it, and 88not just a tag pointing to another commit. 89 90Once this is done, the release should create a signed tag with the 91appropriate tag name: 92``` bash 93git tag -s va.b.c-rcn 94``` 95The releaser will need to make sure that git is configured to use the 96proper signing key, and that the public key is signed by enough parties to 97be trusted. 98 99At this point, the tag can be pushed to GitHub to make the actual release 100happen: 101``` bash 102git push origin HEAD:refs/heads/main 103git push origin va.b.c-rcn 104``` 105 106## Branching after a release 107 108After the final (non-`rc`) a.b.0 release is made, a new branch must 109be created and pushed: 110 111``` bash 112git checkout va.b.c 113git checkout -b va.b-branch 114git push origin va.b-branch 115``` 116 117This branch will be used to generate new incremental `PATCH` releases 118for bug fixes or required minor updates (for example, new `imgtool` features). 119 120## Post release actions 121 122Mark the MCUboot version as a development version. 123 124The version number used should be specified for the next expected release. 125It should be larger than the last release version by incrementing the MAJOR or 126the MINOR number. It is not necessary to define the next version precisely as 127the next release version might still be different as it might be needed to do: 128 129- a patch release 130- a MINOR release while a MAJOR release was expected 131- a MAJOR release while a MINOR release was expected 132 133[semver]: http://semver.org/ 134
