doc/project/release_process.rst

.. _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 6-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.

Release Phases Overview
***********************

Each release cycle consists of a *development phase* followed by a
*stabilization phase*. Release candidates will be created during the
stabilization phase.

During the development phase, all sorts of changes can be merged. This is
called the *merge window* for the main branch for this reason. During the
stabilization phase, the project and its maintainers focus on fixing bugs and
documenting the release. During this time, new features are generally not
accepted. The main branch is in *feature freeze* during the stabilization
phase.

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

    Release Cycle

The milestones for the current major version can be found on the
`Official GitHub Wiki <https://github.com/zephyrproject-rtos/zephyr/wiki/Release-Management>`_.
Information on previous releases can be found :ref:`here <zephyr_release_notes>`.

.. note::

   After each stable release is made, a new "release branch" for that release
   is created.

   For example, after Zephyr stable release v4.4.0 was announced, a new branch
   ``v4.4-branch`` was created. Commits intended for v4.4.x point releases
   (v4.4.1, v4.4.2, etc.) should be proposed with that branch as a target.

   This page currently does not document the point release process in detail.

.. _merge_window:

Merge Window (Development Phase)
================================

After tagging a release, the release managers open the `main branch
<https://github.com/zephyrproject-rtos/zephyr/tree/main>`_ for development for
the next release cycle. We call this time the *merge window* or the
*development phase* for each release. During the merge window, any code which
meets the :ref:`merge_criteria` can be merged into the main branch. Most
changes for each release are made during its merge window.

Each release's merge window lasts approximately five months.

After the merge window, the release team tags the first *release candidate* for
the upcoming release. At that point, the main branch is closed for most feature
development, and the project is in :ref:`feature freeze <feature_freeze>` for
the next release. Feature freeze is described in the next section.

Here is an example timeline for a merge window:

- the merge window opened when `v4.3.0
  <https://github.com/zephyrproject-rtos/zephyr/tree/v4.3.0>`_ was tagged on 13
  November 2025. At this point, the main branch was open for merges for the
  next release, which was v4.4.0.

- the merge window for v4.4.0 closed when `v4.4.0-rc1
  <https://github.com/zephyrproject-rtos/zephyr/tree/v4.4.0-rc1>`_ was tagged
  on 24 March 2026. At this time, the project entered feature freeze for the
  v4.4.0 release.

.. _feature_freeze:

Feature Freeze (Stabilization Phase)
====================================

When the first release candidate is tagged, the release's merge window is
closed. This is called the *feature freeze* or *stabilization phase* for that
release. During feature freeze, no new features will be merged for that release
without a :ref:`tsc` approved exception.

Please be patient during the stabilization phase while waiting for pull request
review for new features.

As mentioned, the exception process for merging features during the feature
freeze requires TSC approval and a justification. As a general rule, if your
pull request is not yet merged and feature freeze is declared, the best thing
to do is to wait for the next :ref:`merge window <merge_window>` to open.

If you believe your feature merits an exception and should be merged during
feature freeze, contact the TSC. See the `TSC wiki
<https://github.com/zephyrproject-rtos/zephyr/wiki/Technical-Steering-Committee-%28TSC%29>`_
page for general contact information.

Here is an example timeline for a feature freeze:

- The feature freeze for v4.4.0 began when `v4.4.0-rc1
  <https://github.com/zephyrproject-rtos/zephyr/tree/v4.4.0-rc1>`_ was tagged
  on 24 March 2026. At that time, new features required a TSC exception
  in order to be merged to the main branch.

- The feature freeze for v4.4.0 ended when `v4.4.0
  <https://github.com/zephyrproject-rtos/zephyr/tree/v4.4.0>`_ was tagged on 14
  April 2026. At that time, the main branch was open again for the next
  release's :ref:`merge window <merge_window>`.

The following sections describe the feature freeze in more detail.

Allowed Changes
---------------

After feature freeze, **only** stabilization-related changes **shall** be accepted:

* Bug fixes addressing functional defects
* Stabilization fixes improving reliability, build stability, or test behavior
* Documentation updates (clarifications, corrections, improvements)
* Tests for existing functionality (no new feature enablement)

For more details on when certain changes are accepted, see :ref:`table <release_milestones>`.

Exceptions to these allowed changes are rare and require both explicit
justification and TSC approval. As a general rule, if a feature misses the
development phase window, it should wait for the next development cycle.

Disallowed Changes
------------------

The following changes **shall not** be accepted after feature freeze:

* New features or feature enhancements
* API changes, unless required to resolve a critical defect
* Refactoring not directly tied to a bug fix or stabilization effort
* New subsystems, drivers, boards, or architectural changes

Issue Tracking during Feature Freeze
************************************

Referencing a GitHub issue in a pull request is **recommended** but **not required**
during feature freeze.

Pull requests **must** include a clear description of:

* The issue being addressed
* The impact of the issue
* How the change resolves the issue

Maintainers and release engineers **may** request additional clarification when
the intent or scope of a pull request is not clear.

Mandatory Issue Usage
=====================

A GitHub issue **shall** be required in the following cases:

* Release blockers
* Fixes targeting maintenance of already released branches


Review and Approval
===================

All pull requests **shall** follow the standard review and approval process.

Maintainers **shall** ensure that:

* Changes comply with this policy
* Scope is minimal and focused on stabilization
* Risk is appropriate for the release phase

Release engineers **may**:

* Reject or defer changes based on risk assessment
* Request changes or additional justification

Risk Expectations
=================

Changes accepted during stabilization **shall** be:

* Minimal in scope
* Low risk
* Adequately tested

Changes introducing significant risk **may** be deferred to a future release,
even if they qualify as bug fixes.

.. _merge_criteria:

Pull Request Merge Criteria
***************************

The following criteria apply during all release phases.

.. figure:: img/img_release_activity.png
      :width: 663px
      :align: center
      :alt: Release Activity

* All :ref:`pr_requirements` must be met.
* Minimal of 2 approvals, including an approval by the designated assignee.
* Pull requests should be reviewed by at least a maintainer or collaborator of
  each affected area; Unless the changes to a given area are considered trivial
  enough, in which case approvals by other affected subsystems
  maintainers/collaborators would suffice.
* Four eye principle on the organisation level. We already require at least 2
  approvals (basic four eye principle), however, such reviews and approvals
  might be unintentionally biased in the case where the submitter is from the
  same organisation as the approvers. To allow for project wide review and
  approvals, the merge criteria is extended with the guidelines below:

  * Changes or additions to common and shared code shall have approvals from
    different organisations (at least one approval from an
    organisation different than the submitters').
    Common and shared code is defined as anything that does not fall under
    :file:`soc`, :file:`boards` and :file:`drivers/*/*`.
  * Changes or additions to hardware support (driver, SoC, boards) shall at
    least have the merger be from a different organisation. This applies only
    to implementation of an API supporting vendor specific hardware and not the
    APIs.
  * Release engineers may make exceptions for areas with contributions primarily
    coming from one organisation and where reviews from other organisations are
    not possible, however, merges shall be completed by a person from a different
    organisation. In such cases, the minimum review period of at least 2 days
    shall be strictly followed to allow for additional reviews.
  * Release engineers shall not merge code changes originating and reviewed
    only by their own organisation. To be able to merge such changes, at least
    one review shall be from a different organisation.

* A minimum review period of 2 business days, 4 hours for trivial changes (see
  :ref:`review_time`).
* Hotfixes can be merged at any time after CI has passed and are excluded from
  most of the conditions listed above.
* All required checks are passing:

  * Device Tree
  * Documentation
  * Code linters (Gitlint, Pylint, Ruff, Sphinx, etc.)
  * Identity/Emails
  * Kconfig
  * License checks
  * Checkpatch (Coding Style)
  * Integration Tests (Via twister) on emulation/simulation platforms
  * Simulated Bluetooth Tests


.. _release_quality_criteria:

Release Quality Criteria
************************

The main motivation is to clearly have the criteria in place that must be met
for a release. This will help define when a release is "done" in terms that most
people can understand and in ways that help new people to understand the process
and participate in creating successful releases:

- The release criteria documents all the requirements of our target audience for
  each Zephyr release
- The target audiences for each release can be different, and may overlap
- The criteria at any given time are not set in stone: there may be requirements
  that have been overlooked, or that are new, and in these cases, the criteria
  should be expanded to ensure all needs are covered.

Below is the high level criteria to be met for each release:

- No blocker bugs / blocking issues
- All relevant tests shall pass on ``Tier 0`` platforms
- All relevant tests shall pass on Tier 0 and 1 platforms (at least 1 per
  architecture/architecture variant/Hardware features)
- All applicable samples/tests shall build on Tiers 0, 1 and 2
- All high and critical static analysis and security issues addressed
- Release Notes are up-to-date.

Blocker Bugs
============

Blocker bug process kicks in during the release process and is in effect after the
feature freeze milestone. An issue labeled as a blocker practically blocks a
release from happening. All blocker bugs shall be resolved before a release is
created.

A fix for a bug that is granted ``blocker`` status can be merged to 'main' and included in
the release all the way until the final release date.

Bugs of moderate severity and higher that have impact on all users are typically
the candidates to be promoted to blocker bugs

Contributors and member of the release engineering team shall follow these
guidelines for release blocker bugs:

- Only mark bugs as blockers if the software (Zephyr) must not be released with
  the bug present.
- All collaborators can add or remove blocking labels.
- Evaluate bugs as potential blockers based on their severity and prevalence.
- Provide detailed rationale whenever adding or removing a blocking label.
- Ensure all blockers have the milestone tagged.
- Release managers have final say on blocking status; contact them with any questions.


.. _release_milestones:

Release Milestones
******************

This table documents milestones associated with each release.

.. list-table:: Release Milestones
   :widths: 15 25 100 25
   :header-rows: 1

   * - Timeline
     - Checkpoint
     - Description
     - Owner
   * - T-5M
     - Planning
     - Finalize dates for release, Assign release owner and agree on project wide goals for this release.
     - TSC
   * - T-7W
     - Review target milestones
     - Finalize target milestones for features in flight.
     - Release Engineering
   * - T-5W
     - Release Announcement
     - Release owner announces feature freeze and timeline for release.
     - Release Manager
   * - T-4W
     - Release Timeline reminder
     - Release owner sends a reminder of the feature freeze and timeline for release.
     - Release Manager
   * - T-3W
     - Feature Freeze (RC1)
     - After RC1, no new features may be introduced. Only stabilization,
       cosmetic updates, bug fixes, documentation improvements, and new tests
       for existing features are permitted.
     - Release Engineering
   * - T-2W
     - 2nd Release Candidate
     - No new features after RC2, ONLY stabilization and cosmetic changes, bug and doc fixes are allowed.
     - Release Manager
   * - T-1W
     - Hard Freeze (RC3)
     - Only blocker bug fixes after RC3, documentation improvements and changes
       to release notes are allowed.
       Release notes need to be complete by this checkpoint. Release Criteria is
       met.
     - Release Manager
   * - T-0W
     - Release
     -
     - Release Manager

.. _release_process_lts:

Long Term Support (LTS) Releases
********************************

Long-term support releases are designed to be supported and maintained
for an extended period and are the recommended release for
products and the auditable branch used for certification.

An LTS release is defined as:

- **Product focused**
- **Extended Stabilisation period**: Allow for more testing and bug fixing
- **Stable APIs**
- **Quality Driven Process**
- **Long Term**: Maintained for an extended period of time (at least 5 years).

Product Focused
===============

Zephyr LTS is the recommended release for product makers with an extended
support and maintenance which includes general stability and bug fixes,
security fixes.

An LTS includes both mature and new features. API and feature maturity is
documented and tracked. The footprint and scope of mature and stable APIs expands
as we move from one LTS to the next giving users access to bleeding edge features
and new hardware while keeping a stable foundation that evolves over time.

Extended Stabilisation Period
=============================

Zephyr LTS development cycle differs from regular releases and has an extended
stabilization period. Feature freeze of regular releases happens 3-4 weeks
before the scheduled release date. The stabilization period for LTS is extended
by 3 weeks with the feature freeze occurring 6-7 weeks before the anticipated
release date. The time between code freeze and release date is extended in this case.

Stable APIs
===========

Zephyr LTS provides a stable and long-lived foundation for developing
products. To guarantee stability of the APIs and the implementation of such
APIs it is required that any release software that makes the core of the OS
went through the Zephyr API lifecycle and stabilized over at least 2 releases.
This guarantees that we release many of the highlighted and core features with
mature and well-established implementations with stable APIs that are
supported during the lifetime of the release LTS.

- API Freeze (LTS - 2)

  - All stable APIs need to be frozen 2 releases before an LTS. APIs can be extended
    with additional features, but the core implementation is not modified. This
    is valid for the following subsystems for example:

    - Device Drivers (i2c.h, spi.h)...
    - Kernel (k_*):
    - OS services (logging,debugging, ..)
    - DTS: API and bindings stability
    - Kconfig

  - New APIs for experimental features can be added at any time as long as they
    are standalone and documented as experimental or unstable features/APIs.
- Feature Freeze (LTS - 1)
  - No new features or overhaul/restructuring of code covering major LTS features.

    - Kernel + Base OS
    - Additional advertised LTS features

  - Auxiliary features on top of and/or extending the base OS and advertised LTS features
    can be added at any time and should be marked as experimental if applicable

Quality Driven Process
======================

The Zephyr project follows industry standards and processes with the goal of
providing a quality oriented releases. This is achieved by providing the
following products to track progress, integrity and quality of the software
components provided by the project:

- Compliance with published coding guidelines, style guides and naming
  conventions and documentation of deviations.
- Static analysis reports

  - Regular static analysis on the complete tree using available commercial and
    open-source tools, and documentation of deviations and false positives.

- Documented components and APIS
- Requirements Catalog
- Verification Plans
- Verification Reports
- Coverage Reports
- Requirements Traceability Matrix (RTM)
- SPDX License Reports

Each release is created with the above products to document the quality and the
state of the software when it was released.

Long Term Support and Maintenance
=================================

LTS releases are published every 2.5 to 3 years and are branched and maintained independently from
the main tree for approximately 5 years after they were released.

Support is provided in three main phases:

- **Phase 1 (first 2 years):** General bug fixes and security fixes, including platform and driver
  fixes.
- **Phase 2 (following 3+ years):** Security and OS stability fixes only.
- **Phase 3:** Extended support may be available through third parties (details to be determined).

Support for a given LTS release (LTS *N*) continues until the initial release of the LTS two
versions ahead (LTS *N+2*). A final release of LTS *N* occurs shortly after the initial release of
LTS *N+2*.

The list of currently supported LTS releases and their EOL dates can be found
:ref:`here <supported_releases>`.

.. mermaid::
   :caption: Long Term Support Release

   gitGraph
       commit id: "3.5"
       commit id: "3.6"
       commit id: "3.7"
       branch "LTS"
       checkout "LTS"
       commit id: "3.7.1"
       commit id: "3.7.2"
       checkout main
       commit id: "4.0"
       commit id: "4.1"

Changes and fixes flow in both directions. However, changes from main branch 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 shall be submitted to
mainline tree 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.

Host Tools Support Policy
*************************

This section documents policies related to host tools required to develop
zephyr applications.

Python Version Policy
=====================

Zephyr tracks the `Python upstream release schedule`_ when determining its minimum supported Python
version.

The minimum supported version is selected to balance long-term support and practical availability in
mainstream, actively supported Linux distributions (e.g. current Ubuntu LTS and Debian Stable
releases).

A Python version is considered for removal when:

* It is approaching or has reached upstream end-of-life (EOL), and
* Newer Python versions are broadly available in current, actively supported major Linux
  distributions.

.. _Python upstream release schedule: https://devguide.python.org/versions/

Hardware Support Tiers
**********************

This section documents a rough set of tiers associated with hardware platforms.
These criteria are not currently formally enforced or evaluated at a board,
architecture, or SoC level.

Tier 0: Emulation Platforms
===========================

- Tests are both built and run in these platforms in CI, and therefore runtime
  failures can block Pull Requests.
- Supported by the Zephyr project itself, commitment to fix bugs in releases.
- One Tier 0 platform is required for each new architecture.
- Bugs reported against platforms of this tier are to be evaluated and treated as
  a general bug in Zephyr and should be dealt with the highest priority.

Tier 1: Supported Platforms
===========================

- Commitment from a specific team to run tests using twister device
  testing for the "Zephyr compatibility test suite" (details TBD)
  on a regular basis using open-source and publicly available drivers.
- Commitment to fix bugs in time for releases. Not supported by "Zephyr Project"
  itself.
- General availability for purchase
- Bugs reported against platforms of this tier are to be evaluated and treated
  as a general bug in Zephyr and should be dealt with medium to high priority.

Tier 2: Community Platforms
===========================

- Platform implementation is available in upstream, no commitment to testing,
  may not be generally available.
- Has a dedicated maintainer who commits to respond to issues / review patches.
- Bugs reported against platforms of this tier are NOT considered as
  a general bug in Zephyr.

Tier 3: Deprecated and unsupported Platforms
============================================

- Platform implementation is available, but no owner or unresponsive owner.
- No commitment to support is available.
- May be removed from upstream if no one works to bring it up to tier 2 or better.
- Bugs reported against platforms of this tier are NOT considered as
  a general bug in Zephyr.

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

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

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
=======


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 main 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 main branch version. Presence of this tag allows generation of
    sensible output for "git describe" on main branch, 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

The final release and each release candidate shall be tagged using the following
steps:

.. 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). You should
    also upload your gpg public key to your GitHub account, since the instructions
    below involve creating signed tags. Alternatively, if you don't have a gpg key,
    you can also use your ssh key for signing.

.. tabs::

    .. tab:: Release Candidate

        .. note::

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

        #. Update the version variables in the :zephyr_file:`VERSION` file
           located in the root of the Git repository to match the version for
           this release candidate. The ``EXTRAVERSION`` variable is used to
           identify the rc[RC Number] value for this candidate::

            EXTRAVERSION = rc1

        #. Post a PR with the updated :zephyr_file:`VERSION` file using
           ``release: Zephyr 1.11.0-rc1`` as the commit subject. Merge
           the PR after successful CI.

        #. Tag and push the version, using an annotated tag::

            $ git pull
            $ git tag -s -m "Zephyr 1.11.0-rc1" v1.11.0-rc1

        #. Verify that the tag has been signed correctly, ``git show`` for the
           tag must contain a signature (look for the ``BEGIN PGP SIGNATURE``
           or ``BEGIN SSH SIGNATURE`` marker in the output)::

            $ git show v1.11.0-rc1

        #. Push the tag::

            $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0-rc1

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

    .. tab:: Final Release

        .. note::

            This section uses tagging 1.11.0 as an example, replace with the
            appropriate final release version.

        When all final release criteria has been met and the final release notes
        have been approved and merged into the repository, the final release version
        will be set and repository tagged using the following procedure:

        #. Update the version variables in the :zephyr_file:`VERSION` file
           located in the root of the Git repository. Set ``EXTRAVERSION``
           variable to an empty string to indicate final release::

            EXTRAVERSION =

        #. Post a PR with the updated :zephyr_file:`VERSION` file using
           ``release: Zephyr 1.11.0`` as the commit subject. Merge
           the PR after successful CI.
        #. Tag and push the version, using two annotated tags::

            $ git pull
            $ git tag -s -m "Zephyr 1.11.0" v1.11.0

        #. Verify that the tag has been signed correctly, ``git show`` for the
           tag must contain a signature (look for the ``BEGIN PGP SIGNATURE``
           or ``BEGIN SSH SIGNATURE`` marker in the output)::

            $ git show v1.11.0

        #. Push the tag::

            $ git push git@github.com:zephyrproject-rtos/zephyr.git v1.11.0

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

            * Copy the overview of ``docs/releases/release-notes-1.11.rst``
              into the release notes textbox and link to the full release notes
              file on docs.zephyrproject.org.

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