.. _release_process:

Release Process
###############

The Zephyr project releases on a time-based cycle, rather than a feature-driven
one. Zephyr releases represent an aggregation of the work of many contributors,
companies, and individuals from the community.

A time-based release process enables the Zephyr project to provide users with a
balance of the latest technologies and features and excellent overall quality. A
roughly 3-month release cycle allows the project to coordinate development of
the features that have actually been implemented, allowing the project to
maintain the quality of the overall release without delays because of one or two
features that are not ready yet.

The Zephyr release model is loosely based on the Linux kernel model:

- Release tagging procedure:

  - linear mode on master,
  - release branches for maintenance after release tagging.
- Each release period will consist of a merge window period followed by one or
  more release candidates on which only stabilization changes, bug fixes, and
  documentation can be merged in.

  - Merge window mode: all changes are accepted (subject to approval from the
    respective maintainers.)
  - When the merge window is closed, the release owner lays a vN-rc1 tag and the
    tree enters the release candidate phase
  - CI sees the tag, builds and runs tests; QA analyses the report from the
    build and test run and gives an ACK/NAK to the build
  - The release owner, with QA and any other needed input, determines if the
    release candidate is a go for release
  - If it is a go for a release, the release owner lays a tag release vN at the
    same point
- Development on new features continues in topic branches. Once features are
  ready, they are submitted to mainline during the merge window period and after
  the release is tagged.

.. figure:: release_cycle.png
    :align: center
    :alt: Release Cycle
    :figclass: align-center
    :width: 80%

    Release Cycle

Merge Window
*************

A relatively straightforward discipline is followed with regard to the merging
of patches for each release.  At the beginning of each development cycle, the
"merge window" is said to be open.  At that time, code which is deemed to be
sufficiently stable (and which is accepted by the development community) is
merged into the mainline tree.  The bulk of changes for a new development cycle
(and all of the major changes) will be merged during this time.

The merge window lasts for approximately two months.  At the end of this time,
the release owner will declare that the window is closed and release the first
of the release candidates.  For the codebase release which is destined to be
0.4.0, for example, the release which happens at the end of the merge window
will be called 0.4.0-rc1.  The -rc1 release is the signal that the time to merge
new features has passed, and that the time to stabilize the next release of the
code base has begun.

Over the next weeks, only patches which fix problems should be submitted to the
mainline.  On occasion, a more significant change will be allowed, but such
occasions are rare and require a TSC approval (Change Control Board). As a
general rule, if you miss the merge window for a given feature, the best thing
to do is to wait for the next development cycle.  (An occasional exception is
made for drivers for previously unsupported hardware; if they do not touch any
other in-tree code, they cannot cause regressions and should be safe to add at
any time).

As fixes make their way into the mainline, the patch rate will slow over time.
The mainline release owner releases new -rc drops once or twice a week; a normal
series will get up to somewhere between -rc4 and -rc6 before the code base is
considered to be sufficiently stable and the final 0.4.x release is made.

At that point, the whole process starts over again.

.. figure:: merge_window.png
    :align: center
    :alt: Merge Window
    :figclass: align-center
    :width: 80%

    Merge Window

Here is the description of the various moderation levels:

- Low:

  - Major New Features
  - Bug Fixes
  - Refactoring
  - Structure/Directory Changes
- Medium:

  - Bug Fixes, all priorities
  - Enhancements
  - Minor "self-contained" New Features
- High:

  - Bug Fixes: P1 and P2
  - Documentation + Test Coverage

Releases
*********

The following syntax should be used for releases and tags in Git:

- Release [Major].[Minor].[Patch Level]
- Release Candidate [Major].[Minor].[Patch Level]-rc[RC Number]
- Tagging:

  - v[Major].[Minor].[Patch Level]-rc[RC Number]
  - v[Major].[Minor].[Patch Level]
  - v[Major].[Minor].99 - A tag applied to master branch to signify that work on
    v[Major].[Minor+1] has started. For example, v1.7.99 will be tagged at the
    start of v1.8 process. The tag corresponds to
    VERSION_MAJOR/VERSION_MINOR/PATCHLEVEL macros as defined for a
    work-in-progress master version. Presence of this tag allows generation of
    sensible output for "git describe" on master, as typically used for
    automated builds and CI tools.


.. figure:: release_flow.png
    :align: center
    :alt: Releases
    :figclass: align-center
    :width: 80%

    Zephyr Code and Releases


Long Term Support (LTS)
=======================

Long-term support releases are designed to be supported for a longer than normal
period and will be the basis for products and certification for various usages.

An LTS release is made every 2 years and is branched and maintained
independently from the mainline tree.

An LTS release will be branched and maintained independently of the mainline
tree.


.. figure:: lts.png
    :align: center
    :alt: Long Term Support Release
    :figclass: align-center
    :width: 80%

    Long Term Support Release

Changes and fixes flow in both directions. However, changes from master to an
LTS branch will be limited to fixes that apply to both branches and for existing
features only.

All fixes for an LTS branch that apply to the mainline tree are pushed to
mainline as well.


Auditable Code Base
===================

An auditable code base is to be established from a defined subset of Zephyr OS
features and will be limited in scope. The LTS,  development tree, and the
auditable code bases shall be kept in sync after the audit branch is created,
but with a more rigorous process in place for adding new features into the audit
branch used for certification.

This process will be applied before new features move into the
auditable code base.

The initial and subsequent certification targets will be decided by the Zephyr project
governing board.

Processes to achieve selected certification will be determined by the Security and
Safety Working Groups and coordinated with the TSC.


Release Procedure
******************

This section documents the Release manager responsibilities so that it serves as
a knowledge repository for Release managers.

Milestones
==========

The following graphic shows the timeline of phases and milestones associated
with each release:

.. figure:: milestones.png
    :align: center
    :alt: Release Milestones
    :figclass: align-center
    :width: 80%

    Release milestones

This shows how the phases and milestones of one release overlap with those of
the next release:


.. figure:: milestones2.png
    :align: center
    :alt: Release Milestones
    :figclass: align-center
    :width: 80%

    Release milestones with planning


.. csv-table:: Milestone Description
   :header: "Milestone", "Description", "Definition"
   :widths: auto


   "P0","Planning Kickoff","Start Entering Requirements"
   "P1","","TSC Agrees on Major Features and Schedule"
   "M0","Merge Window Open","All features, Sized, and AssignedMerge Window Is Opened"
   "M1","M1 Checkpoint","Major Features Ready for Code Reviews |br| Test Plans Reviewed and Approved"
   "M2","Feature Merge Window Close","Feature Freeze |br| Feature Development Complete (including Code Reviews and Unit Tests Passing) |br| P1 Stories Implemented |br| Feature Merge Window Is Closed |br| Test Development Complete |br| Technical Documentation Created/Updated and Ready for Review |br| CCB Control Starts"
   "M3","Code Freeze","Code Freeze |br| RC3 Tagged and Built"
   "M4","Release","TSC Reviews the Release Criteria Report and Approves Release
   |br| Final RC Tagged |br| Make the Release"

Release Checklist
=================

Each release has a GitHub issue associated with it that contains the full
checklist. After a release is complete, a checklist for the next release is
created.

Tagging
=======

.. note::

    This section uses tagging 1.11.0-rc1 as an example, replace with the
    appropriate version.

Every time a release candidate (or the final release) needs to be tagged, the
following steps need to be followed:

.. note::

    Tagging needs to be done via explicit git commands and not via GitHub's release
    interface.  The GitHub release interface does not generate annotated tags (it
    generates 'lightweight' tags regardless of release or pre-release).

#. Update the :zephyr_file:`VERSION` file in the root of the Git repository. If it's a
release candidate, use ``EXTRAVERSION`` variable::

    EXTRAVERSION = rc1

#. Commit the update to the :zephyr_file:`VERSION` file, use ``release:`` as a commit
   tag.
#. Check that CI has completed successfully before tagging.
#. Tag and push the version, using annotated tags:

   * If it's a release candidate::

      $ git tag -a v1.11.0-rc1
      <Use "Zephyr 1.11.0-rc1" as the tag annotation>
      $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1

  * If it's a release::

      $ git tag -a v1.11.0
      <Use "Zephyr 1.11.0" as the tag annotation>
      $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0

      $ git tag -a zephyr-v1.11.0
      <Use "Zephyr 1.11.0" as the tag annotation>
      $ git push git@github.com:zephyrproject-rtos/zephyr.git zephyr-v1.11.0

#. If it's a release candidate, create a shortlog of changes between the
   previous release::

    $ git shortlog v1.10.0..v.1.11.0-rc1

#. Find the new tag at the top of the releases page, edit the release with the
   ``Edit`` button and then do the following:

  * If it's a release candidate:

    * Name it ``Zephyr 1.11.0-rc1``
    * Copy the shortlog into the release notes textbox (don't forget to quote it
      properly so it shows as unformatted text in Markdown)
    * Check the "This is a pre-release" checkbox
  * If it's a release:

    * Name it ``Zephyr 1.11.0``
    * Copy the full content of ``docs/release-notes-1.11.rst`` into the the
      release notes textbox
    * Copy the full list of GitHub issues closed with this release into the
      release notes textbox (see below on how to generate this list)

#. Send an email to the mailing lists (``announce`` and ``devel``) with a link
   to the release

Listing all closed GitHub issues
=================================

The release notes for a final release contain the list of GitHub issues that
have been closed during the development process of that release.

In order to obtain the list of issues closed during the release development
cycle you can do the following:

#. Look for the last release before the current one and find the day it was
   tagged::

    $ git show zephyr-v1.10.0
    tag zephyr-v1.10.0
    Tagger: Kumar Gala <kumar.gala@linaro.org>
    Date:   Fri Dec 8 14:26:35 2017 -0600


#. Use available release tools to list all the issues that have been closed
   between that date and the day of the release.