Skip to content

doc: release process fixes/tweaks #98253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 29, 2025
+97 −122
Merged

doc: release process fixes/tweaks #98253

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4c281ac
doc: release: move merge criteria under release process
nashif Oct 25, 2025
7557361
doc: release: release process tweaks/fixes
nashif Oct 25, 2025
0fe485b
doc: release: move tagging schema under release process
nashif Oct 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 0 additions & 68 deletions doc/project/project_roles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,72 +349,4 @@ Generic guidelines for deciding and filling in the Maintainers' list
implementation


Release Activity
################

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

.. _merge_criteria:

Merge Criteria
++++++++++++++

* 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

* Planned

* Footprint
* Code coverage
* Coding Guidelines
* Static Analysis (Coverity)
* Documentation coverage (APIs)


.. _Zephyr Contributor Badge form: https://forms.gle/oCw9iAPLhUsHTapc8
151 changes: 97 additions & 54 deletions doc/project/release_process.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,33 +9,15 @@ 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 4-month release cycle allows the project to coordinate development of
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.

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

- Release tagging procedure:

- linear mode on main branch,
- release branches for maintenance after release tagging.
- Each release period will consist of a development phase followed by a
stabilization phase. Release candidates will be tagged during the
stabilization phase. During the stabilization phase, only stabilization
changes such as bug fixes and documentation will be merged unless granted a
special exemption by the Technical Steering Committee.

- Development phase: all changes are considered and merged, subject to
approval from the respective maintainers.
- Stabilisation phase: the release manager creates a vN-rc1 tag and the tree
enters the stabilization phase
- CI sees the tag, builds and runs tests; Test teams analyse the report from the
build and test run and give an ACK/NAK to the build
- The release owner, with test teams 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
Each release period will consist of a development phase followed by a
stabilization phase. Release candidates will be created during the stabilization
phase.


.. figure:: release_cycle.svg
:align: center
Expand All @@ -51,6 +33,7 @@ The Zephyr release model was loosely based on the Linux kernel model:
`Official GitHub Wiki <https://github.com/zephyrproject-rtos/zephyr/wiki/Release-Management>`_.
Information on previous releases can be found :ref:`here <zephyr_release_notes>`.


Development Phase
*****************

Expand All @@ -72,9 +55,9 @@ code base has begun.
Stabilization Phase
*******************

Over the next weeks and depending on the release milestone, only stabilization,
cosmetic changes, tests, bug and doc fixes are allowed (See :ref:`table
<release_milestones>` below).
Over the following weeks and depending on the release milestone, only stabilization,
cosmetic updates, bug fixes, documentation improvements, and new tests for
existing features are permitted. (See :ref:`table <release_milestones>` below).

On occasion, more significant changes and new features will be allowed, but such
occasions are rare and require a TSC approval and a justification. As a general
Expand All @@ -92,6 +75,63 @@ at which point the final 3.1.0 release is made.

At that point, the whole process starts over again.

.. _merge_criteria:

Merge Criteria
**************

.. 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 Criteria
Expand Down Expand Up @@ -177,16 +217,18 @@ Release Milestones
- Release Manager
* - T-3W
- Feature Freeze (RC1)
- No new features after RC1, ONLY stabilization and cosmetic changes, bug and doc
fixes are allowed. New tests for existing features are also allowed.
- 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 and changes to release notes are allowed.
- 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
Expand All @@ -199,31 +241,6 @@ Release Milestones
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 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

.. _release_process_lts:

Long Term Support (LTS)
Expand Down Expand Up @@ -437,6 +454,32 @@ 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:

Expand Down