general/releases.rst - OP-TEE/optee_docs - TrustedFirmware Git Browser

 .. _releases:

 Releases
 ########

 .. _releases_cadance:

 Cadence
 *******
 New versions of OP-TEE are released four times a year, i.e., quarterly releases.

 .. _release_dates:

 Release dates
 =============
 Starting from version 3.10.0 we track the old and also show the releases being
 planned for the future in the table below. The dates will tell whether it is an
 old, upcoming or future release.

 +---------------+--------------+
 | Version       | Release date |
 +===============+==============+
 | OP-TEE 3.13.0 | 16/Apr/21    |
 +---------------+--------------+
 | OP-TEE 3.12.0 | 15/Jan/21    |
 +---------------+--------------+
 | OP-TEE 3.11.0 | 16/Oct/20    |
 +---------------+--------------+
 | OP-TEE 3.10.0 | 21/Aug/20    |
 +---------------+--------------+

 .. _releases_changelog:

 Changelog
 *********
 The changelog is stored in the :ref:`optee_os` git (CHANGELOG.md_). There you
 can see what has been done between the different releases in terms of commits as
 well as pull requests.

 .. _releases_versioning_schema:

 Versioning schema
 *****************
 OP-TEE follows `Semantic Versioning 2.0.0`_. What that means in practice is well
 described at the link just shown.

 .. _releases_release_procedure:

 Release procedure
 *****************
 There are certain steps that needs to be done when making a release. This
 checklist here serves as guidance to the one in charge of making a new release.
 Roughly start with this 2-3 weeks before the targeted release date.

 tl;dr
 =====
 .. list-table:: Short version of the OP-TEE release procedure
     :widths: 60 300 10
     :header-rows: 1

     * - When
         (Tminus)
       - Action
       - Example

     * - 3w
       - Create release pull request
       - `PR#3099`_

     * - 3w
       - Inform maintainers about upcoming release
       -

     * - 1w
       - Increment the revision number in `mk/config.mk`_
       - ``CFG_OPTEE_REVISION_MAJOR ?= 3`` ``CFG_OPTEE_REVISION_MINOR ?= x``

     * - 1w
       - Create release candidate tag in optee_* + build.git
       - git tag -a 3.x.y-rc1 -m "3.x.y-rc1"

     * - 1w
       - Let maintainers know about the release candidate tag
       -

     * - 1w
       - Test platform builds / devices
       -

     * - Release day
       - Update CHANGELOG.md_
       - `changelog example`_

     * - Release day
       - Collect/merge ``Tested-By`` tags
       - `commit example`_

     * - Release day
       - Create release tag in optee_* + build.git + linux.git
       - | git tag -a 3.x.y -m "3.x.y"
         | git tag -a optee-3.x.y -m "optee-3.x.y" # (Linux)

     * - Release day
       - Create release branch in :ref:`manifest`
       - git checkout -b 3.x.y origin/master

     * - Release day
       - Update manifest XML-files
       - `3.6.0 stable`_

     * - Release day
       - Inform maintainers and stakeholder that release has been completed.
       -


 Long version
 ============

     1. Create a "release pull request" at GitHub ought to collect ``Tested-By``
        tags from various maintainers. As an example, see `PR#3099`_.

     2. Send email to all maintainers to let them know about the upcoming
        release. The addresses to the maintainers can be found in the
        MAINTAINERS_ file.

        .. hint::
             With this command you will get all email addresses

             .. code-block:: bash

                 $ scripts/get_maintainer.py --release-to

     3. Increment the revision number in `mk/config.mk`:
        ``CFG_OPTEE_REVISION_MAJOR`` and ``CFG_OPTEE_REVISION_MINOR``. These
        values are made available to TAs and to the Normal World driver at boot
        time.

     4. Create a release candidate (RC) tag (annotated tag, i.e., ``git tag -a
        3.x.y-rc1 -m "3.x.y-rc1"``) in the following gits
        ``optee_*`` and ``build.git``. One way to do it is like this

        .. code-block:: bash

             $ export VER=3.x.y-rc1
             $ for d in optee* build; do ( cd $d; git tag -a $VER -m $VER ); done
             $ for d in optee* build; do ( cd $d; git push origin $VER ); done


     5. Send a follow up email to all maintainers to let them know that there is
        a release tag ready to be tested on their devices for the platforms that
        they are maintaining.

     6. In case major regressions are found, then fix those and create a another
        release candidate tag (i.e., repeat step 3 and 4 until there are no
        remaining issues left).

     7. On release day: Update CHANGELOG.md_ see this `changelog example`_ to see
        how that should look like.

     8. Collect all tags (``Tested-By`` etc) from maintainers and use those in
        the commit message, for an example see this `commit example`_.

     9. Create a release tag (annotated tag, i.e., ``git tag -a 3.x.y -m
        "3.x.y"``) in the following gits ``optee_*`` and ``build.git``. Tag the
        tip of the ``optee`` branch in ``linux.git``, the name of the tag has
        to be prefixed with ``optee-`` to avoid confusions. For instance:
        ``git tag -a optee-3.x.y -m "optee-3.x.y"``.

        .. hint::

             You can use the same steps as in step 4, when creating the tags.

     10. Create a new branch in :ref:`manifest` from ``master`` where the name
         corresponds to the release you are preparing. I.e., ``git checkout -b
         3.x.y origin/master``.


     11. Update all :ref:`manifest` XML-files in the :ref:`manifest` git, so they
         refer to the tag in the release we are working with (see `3.6.0 stable`_
         commit as an example). This can be done with the make_stable.sh_ script.
         Now it is also time to push the new branch and tag it. Example:

        .. code-block:: bash

             $ export VER=3.x.y
             $ cd manifest
             $ ./make_stable.sh -o -r $VER
             $ git diff  # make sure everything looks good
             $ git commit -a -m "OP-TEE $VER stable"
             $ git remote add upstream git@github.com:OP-TEE/manifest
             $ git push upstream
             $ git tag -a $VER -m $VER
             $ git push upstream tag $VER

     12. Send a last email to maintainers and other stakeholders telling that the
         release has been completed.


 .. _3.6.0 stable: https://github.com/OP-TEE/manifest/commit/f181e959c21baddce82552104daf81a25f8fd898
 .. _CHANGELOG.md: https://github.com/OP-TEE/optee_os/blob/master/CHANGELOG.md
 .. _changelog example: https://github.com/OP-TEE/optee_os/commit/f398d4923da875370149ffee45c963d7adb41495#diff-4ac32a78649ca5bdd8e0ba38b7006a1e
 .. _commit example: https://github.com/OP-TEE/optee_os/commit/f398d4923da875370149ffee45c963d7adb41495
 .. _MAINTAINERS: https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS
 .. _make_stable.sh: https://github.com/OP-TEE/manifest/blob/master/make_stable.sh
 .. _PR#3099: https://github.com/OP-TEE/optee_os/pull/3099
 .. _Semantic Versioning 2.0.0: https://semver.org
 .. _mk/config.mk: https://github.com/OP-TEE/optee_os/blob/master/mk/config.mk
	.. _releases:

	Releases
	########

	.. _releases_cadance:

	Cadence
	*******
	New versions of OP-TEE are released four times a year, i.e., quarterly releases.

	.. _release_dates:

	Release dates
	=============
	Starting from version 3.10.0 we track the old and also show the releases being
	planned for the future in the table below. The dates will tell whether it is an
	old, upcoming or future release.

	+---------------+--------------+
	\| Version \| Release date \|
	+===============+==============+
	\| OP-TEE 3.13.0 \| 16/Apr/21 \|
	+---------------+--------------+
	\| OP-TEE 3.12.0 \| 15/Jan/21 \|
	+---------------+--------------+
	\| OP-TEE 3.11.0 \| 16/Oct/20 \|
	+---------------+--------------+
	\| OP-TEE 3.10.0 \| 21/Aug/20 \|
	+---------------+--------------+

	.. _releases_changelog:

	Changelog
	*********
	The changelog is stored in the :ref:`optee_os` git (CHANGELOG.md_). There you
	can see what has been done between the different releases in terms of commits as
	well as pull requests.

	.. _releases_versioning_schema:

	Versioning schema
	*****************
	OP-TEE follows `Semantic Versioning 2.0.0`_. What that means in practice is well
	described at the link just shown.

	.. _releases_release_procedure:

	Release procedure
	*****************
	There are certain steps that needs to be done when making a release. This
	checklist here serves as guidance to the one in charge of making a new release.
	Roughly start with this 2-3 weeks before the targeted release date.

	tl;dr
	=====
	.. list-table:: Short version of the OP-TEE release procedure
	:widths: 60 300 10
	:header-rows: 1

	* - When
	(Tminus)
	- Action
	- Example

	* - 3w
	- Create release pull request
	- `PR#3099`_

	* - 3w
	- Inform maintainers about upcoming release
	-

	* - 1w
	- Increment the revision number in `mk/config.mk`_
	- ``CFG_OPTEE_REVISION_MAJOR ?= 3`` ``CFG_OPTEE_REVISION_MINOR ?= x``

	* - 1w
	- Create release candidate tag in optee_* + build.git
	- git tag -a 3.x.y-rc1 -m "3.x.y-rc1"

	* - 1w
	- Let maintainers know about the release candidate tag
	-

	* - 1w
	- Test platform builds / devices
	-

	* - Release day
	- Update CHANGELOG.md_
	- `changelog example`_

	* - Release day
	- Collect/merge ``Tested-By`` tags
	- `commit example`_

	* - Release day
	- Create release tag in optee_* + build.git + linux.git
	- \| git tag -a 3.x.y -m "3.x.y"
	\| git tag -a optee-3.x.y -m "optee-3.x.y" # (Linux)

	* - Release day
	- Create release branch in :ref:`manifest`
	- git checkout -b 3.x.y origin/master

	* - Release day
	- Update manifest XML-files
	- `3.6.0 stable`_

	* - Release day
	- Inform maintainers and stakeholder that release has been completed.
	-


	Long version
	============

	1. Create a "release pull request" at GitHub ought to collect ``Tested-By``
	tags from various maintainers. As an example, see `PR#3099`_.

	2. Send email to all maintainers to let them know about the upcoming
	release. The addresses to the maintainers can be found in the
	MAINTAINERS_ file.

	.. hint::
	With this command you will get all email addresses

	.. code-block:: bash

	$ scripts/get_maintainer.py --release-to

	3. Increment the revision number in `mk/config.mk`:
	``CFG_OPTEE_REVISION_MAJOR`` and ``CFG_OPTEE_REVISION_MINOR``. These
	values are made available to TAs and to the Normal World driver at boot
	time.

	4. Create a release candidate (RC) tag (annotated tag, i.e., ``git tag -a
	3.x.y-rc1 -m "3.x.y-rc1"``) in the following gits
	``optee_*`` and ``build.git``. One way to do it is like this

	.. code-block:: bash

	$ export VER=3.x.y-rc1
	$ for d in optee* build; do ( cd $d; git tag -a $VER -m $VER ); done
	$ for d in optee* build; do ( cd $d; git push origin $VER ); done


	5. Send a follow up email to all maintainers to let them know that there is
	a release tag ready to be tested on their devices for the platforms that
	they are maintaining.

	6. In case major regressions are found, then fix those and create a another
	release candidate tag (i.e., repeat step 3 and 4 until there are no
	remaining issues left).

	7. On release day: Update CHANGELOG.md_ see this `changelog example`_ to see
	how that should look like.

	8. Collect all tags (``Tested-By`` etc) from maintainers and use those in
	the commit message, for an example see this `commit example`_.

	9. Create a release tag (annotated tag, i.e., ``git tag -a 3.x.y -m
	"3.x.y"``) in the following gits ``optee_*`` and ``build.git``. Tag the
	tip of the ``optee`` branch in ``linux.git``, the name of the tag has
	to be prefixed with ``optee-`` to avoid confusions. For instance:
	``git tag -a optee-3.x.y -m "optee-3.x.y"``.

	.. hint::

	You can use the same steps as in step 4, when creating the tags.

	10. Create a new branch in :ref:`manifest` from ``master`` where the name
	corresponds to the release you are preparing. I.e., ``git checkout -b
	3.x.y origin/master``.


	11. Update all :ref:`manifest` XML-files in the :ref:`manifest` git, so they
	refer to the tag in the release we are working with (see `3.6.0 stable`_
	commit as an example). This can be done with the make_stable.sh_ script.
	Now it is also time to push the new branch and tag it. Example:

	.. code-block:: bash

	$ export VER=3.x.y
	$ cd manifest
	$ ./make_stable.sh -o -r $VER
	$ git diff # make sure everything looks good
	$ git commit -a -m "OP-TEE $VER stable"
	$ git remote add upstream git@github.com:OP-TEE/manifest
	$ git push upstream
	$ git tag -a $VER -m $VER
	$ git push upstream tag $VER

	12. Send a last email to maintainers and other stakeholders telling that the
	release has been completed.


	.. _3.6.0 stable: https://github.com/OP-TEE/manifest/commit/f181e959c21baddce82552104daf81a25f8fd898
	.. _CHANGELOG.md: https://github.com/OP-TEE/optee_os/blob/master/CHANGELOG.md
	.. _changelog example: https://github.com/OP-TEE/optee_os/commit/f398d4923da875370149ffee45c963d7adb41495#diff-4ac32a78649ca5bdd8e0ba38b7006a1e
	.. _commit example: https://github.com/OP-TEE/optee_os/commit/f398d4923da875370149ffee45c963d7adb41495
	.. _MAINTAINERS: https://github.com/OP-TEE/optee_os/blob/master/MAINTAINERS
	.. _make_stable.sh: https://github.com/OP-TEE/manifest/blob/master/make_stable.sh
	.. _PR#3099: https://github.com/OP-TEE/optee_os/pull/3099
	.. _Semantic Versioning 2.0.0: https://semver.org
	.. _mk/config.mk: https://github.com/OP-TEE/optee_os/blob/master/mk/config.mk