[V2,3/3] ref-manual/release-process.rst: add patch acceptance policies and stable point release upgrades

From: Chen Qi <Qi.Chen@windriver.com>

Document patch acceptance policies and stable point release upgrades,
including criteria for qualifying upstreams and how stable release
regexes constrain version checks.

Signed-off-by: Chen Qi <Qi.Chen@windriver.com>
---
 documentation/ref-manual/release-process.rst | 114 +++++++++++++++++++
 1 file changed, 114 insertions(+)

Hi,

On Tue Jun 16, 2026 at 7:20 AM CEST, Chen Qi via lists.yoctoproject.org wrote:
> From: Chen Qi <Qi.Chen@windriver.com>
>
> Document patch acceptance policies and stable point release upgrades,
> including criteria for qualifying upstreams and how stable release
> regexes constrain version checks.
>
> Signed-off-by: Chen Qi <Qi.Chen@windriver.com>
> ---
>  documentation/ref-manual/release-process.rst | 114 +++++++++++++++++++
>  1 file changed, 114 insertions(+)
>
> diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
> index a55187c14..fa712869a 100644
> --- a/documentation/ref-manual/release-process.rst
> +++ b/documentation/ref-manual/release-process.rst
> @@ -127,6 +127,120 @@ stable release.
>     exception to this policy occurs when there is a strong reason such as
>     the fix happens to also be the preferred upstream approach.
>  
> +.. _ref-stable-lts-patch-acceptance-policies:
> +
> +Stable/LTS Patch Acceptance Policies
> +=====================================
> +
> +All changes must have already been accepted into the current master release
> +and any other release still within its stable support window.
> +
> +**Acceptable:**
> +
> +-  Security and CVE fixes
> +-  Fixes for bugs
> +-  Version updates which follow an upstream stable series or LTS that aligns with
> +   the original release (based on compatibility). See
> +   :ref:`ref-manual/release-process:stable point release upgrades` for details.
> +
> +.. note::
> +
> +   Once :term:`UPSTREAM_STABLE_RELEASE_REGEX` has been accepted for a recipe,
> +   version upgrades matching the accepted pattern are considered acceptable
> +   by default (with the usual ability to reject if upstream fails to follow
> +   their own stable guidelines).
> +
> +**Potentially acceptable:**
> +
> +-  Fixes so the codebase works with newly released distros

I'm not sure I understand this. Could you expand this with an example?

> +
> +**Unacceptable:**
> +
> +-  General version upgrades
> +-  New features
> +-  ABI/API breakage
> +-  Metadata improvements and refactoring, unless this is a dependency of a
> +   required fix
> +

Should we also mention that some backports / patches can be exceptions to these
rules if it is approved by the TSC?

> +.. _ref-stable-point-release-upgrades:
> +
> +Stable Point Release Upgrades
> +=============================
> +
> +Some upstream projects maintain stable branches that only collect bug fixes
> +and security patches — similar to the Yocto Project's own stable release

s/—/---/

Did you use an LLM to work on these patches? If so, please mention it with the
AI-Generated patch trailer as per our policy:
https://docs.yoctoproject.org/contributor-guide/submit-changes.html#acceptance-of-ai-generated-code

> +policy. For recipes tracking such upstreams, it is possible to perform
> +*stable point release upgrades* (e.g. upgrading from 1.0.2 to 1.0.3) rather
> +than only accepting backported patches. This is the mechanism behind the
> +"acceptable: version updates which follow an upstream stable series" policy above.
> +
> +Criteria for Qualifying Upstreams
> +---------------------------------
> +
> +Setting :term:`UPSTREAM_STABLE_RELEASE_REGEX` for a recipe means that certain
> +version upgrades can be confidently treated as stable point upgrades under
> +OpenEmbedded's criteria. The Automated Upgrade Helper (AUH) will then

Link to AUH maybe:

s/The Automated Upgrade Helper (AUH)/The :ref:`Automated Upgrade Helper (AUH) <dev-manual/upgrading-recipes.:Using the Auto Upgrade Helper (AUH)>`/

> +automatically send patches to upgrade recipes with this variable set during
> +stable releases.
> +
> +.. note::
> +
> +   Patches to upgrade recipes without this variable may still be submitted
> +   for stable branches, but the barrier for acceptance is high. The commit
> +   message needs to justify that the version upgrade follows our stable
> +   branch policy or that there is an exceptional reason for taking the
> +   upgrade.
> +
> +A recipe may have :term:`UPSTREAM_STABLE_RELEASE_REGEX` set based on the
> +following criteria:
> +
> +1. **Upstream stable branches exist** --- the upstream project maintains
> +   branches named with a stable version component, and there is evidence
> +   that these branches only collect bug-fix and security-fix changes
> +   (no new features or ABI/API breakage). For example, util-linux version
> +   ``2.41.3`` has three parts in its version and upstream has branches like
> +   ``stable/v2.41`` with two parts. This demonstrates that bumps in the
> +   third part (e.g. ``2.41.3`` to ``2.41.4``) are stable point releases.
> +   Similarly, systemd maintains ``stable/v259-stable``.
> +
> +2. **Upstream maintainer confirmation** --- the upstream project's maintainer
> +   explicitly confirms that a bump in a certain part of the version is
> +   bug-fix only.
> +
> +3. **Clear historical or common-sense evidence** --- the project's change
> +   history clearly shows that a certain class of version bump is bug-fix
> +   only, or it is widely understood convention. For example, openssh's
> +   ``p`` suffix increments (``10.2p1`` to ``10.2p2``) and kmod's patch-level
> +   bumps are historically bug-fix only releases.
> +
> +.. note::
> +
> +   Patches to set :term:`UPSTREAM_STABLE_RELEASE_REGEX` are sent against the
> +   master branch first and follow the normal review process. Once accepted on
> +   master they may be backported to stable release branches. Exceptions may be
> +   made when necessary, e.g. setting :term:`UPSTREAM_STABLE_RELEASE_REGEX` on
> +   a stable branch for a recipe which has since been removed on master.
> +
> +How Stable Release Regexes Work
> +-------------------------------
> +
> +The stable point upgrade mechanism uses a *filter regex* to constrain the
> +upstream version check so that only versions within the same stable series
> +are considered. When a recipe sets :term:`UPSTREAM_STABLE_RELEASE_REGEX`, the
> +version-checking infrastructure in BitBake's fetchers (git, wget, crate)
> +applies that regex to filter discovered upstream versions. Only versions
> +matching the regex are considered as upgrade candidates.
> +
> +For example, if a recipe is currently at version ``1.4.2`` and the regex is
> +``^1\.4(\.\d+)*$``, then version ``1.4.7`` would be a valid upgrade candidate
> +but ``1.5.0`` would not.
> +
> +For recipes whose version uses a dot-separated scheme, the
> +:ref:`ref-classes-upstream-stable-release-point` class can automatically
> +generate this regex. For other versioning schemes, set
> +:term:`UPSTREAM_STABLE_RELEASE_REGEX` directly in the recipe.
> +
> +

Extra newline not needed here.

>  .. _ref-long-term-support-releases:
>  
>  Long Term Support Releases


Antonin

Hi Antonin,

Thanks for you review.
I'll send out V3 according to your suggestions.
For answers to your questions, see comments inline.

On 6/16/26 22:47, Antonin Godard via lists.yoctoproject.org wrote:
> Hi,
>
> On Tue Jun 16, 2026 at 7:20 AM CEST, Chen Qi via lists.yoctoproject.org wrote:
>> From: Chen Qi <Qi.Chen@windriver.com>
>>
>> Document patch acceptance policies and stable point release upgrades,
>> including criteria for qualifying upstreams and how stable release
>> regexes constrain version checks.
>>
>> Signed-off-by: Chen Qi <Qi.Chen@windriver.com>
>> ---
>>   documentation/ref-manual/release-process.rst | 114 +++++++++++++++++++
>>   1 file changed, 114 insertions(+)
>>
>> diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
>> index a55187c14..fa712869a 100644
>> --- a/documentation/ref-manual/release-process.rst
>> +++ b/documentation/ref-manual/release-process.rst
>> @@ -127,6 +127,120 @@ stable release.
>>      exception to this policy occurs when there is a strong reason such as
>>      the fix happens to also be the preferred upstream approach.
>>   
>> +.. _ref-stable-lts-patch-acceptance-policies:
>> +
>> +Stable/LTS Patch Acceptance Policies
>> +=====================================
>> +
>> +All changes must have already been accepted into the current master release
>> +and any other release still within its stable support window.
>> +
>> +**Acceptable:**
>> +
>> +-  Security and CVE fixes
>> +-  Fixes for bugs
>> +-  Version updates which follow an upstream stable series or LTS that aligns with
>> +   the original release (based on compatibility). See
>> +   :ref:`ref-manual/release-process:stable point release upgrades` for details.
>> +
>> +.. note::
>> +
>> +   Once :term:`UPSTREAM_STABLE_RELEASE_REGEX` has been accepted for a recipe,
>> +   version upgrades matching the accepted pattern are considered acceptable
>> +   by default (with the usual ability to reject if upstream fails to follow
>> +   their own stable guidelines).
>> +
>> +**Potentially acceptable:**
>> +
>> +-  Fixes so the codebase works with newly released distros
> I'm not sure I understand this. Could you expand this with an example?
I think a typical example is uninative-tarball updates. I'll add this 
example.
>
>> +
>> +**Unacceptable:**
>> +
>> +-  General version upgrades
>> +-  New features
>> +-  ABI/API breakage
>> +-  Metadata improvements and refactoring, unless this is a dependency of a
>> +   required fix
>> +
> Should we also mention that some backports / patches can be exceptions to these
> rules if it is approved by the TSC?
Got it. I'll add a note here that exceptions must be approved by the TSC.
>
>> +.. _ref-stable-point-release-upgrades:
>> +
>> +Stable Point Release Upgrades
>> +=============================
>> +
>> +Some upstream projects maintain stable branches that only collect bug fixes
>> +and security patches — similar to the Yocto Project's own stable release
> s/—/---/
>
> Did you use an LLM to work on these patches? If so, please mention it with the
> AI-Generated patch trailer as per our policy:
> https://docs.yoctoproject.org/contributor-guide/submit-changes.html#acceptance-of-ai-generated-code
Yes. Thanks for the info.
>
>> +policy. For recipes tracking such upstreams, it is possible to perform
>> +*stable point release upgrades* (e.g. upgrading from 1.0.2 to 1.0.3) rather
>> +than only accepting backported patches. This is the mechanism behind the
>> +"acceptable: version updates which follow an upstream stable series" policy above.
>> +
>> +Criteria for Qualifying Upstreams
>> +---------------------------------
>> +
>> +Setting :term:`UPSTREAM_STABLE_RELEASE_REGEX` for a recipe means that certain
>> +version upgrades can be confidently treated as stable point upgrades under
>> +OpenEmbedded's criteria. The Automated Upgrade Helper (AUH) will then
> Link to AUH maybe:
>
> s/The Automated Upgrade Helper (AUH)/The :ref:`Automated Upgrade Helper (AUH) <dev-manual/upgrading-recipes.:Using the Auto Upgrade Helper (AUH)>`/

I read the README file 
(https://git.yoctoproject.org/yocto-docs/tree/documentation/README?id=768cbc958#n31) 
before I started modifying things.

I thought "self-contained" means no reference to other manuals. But I 
just grepped ref-manual and it does reference other manuals.

I'll modify this in V3.

>
>> +automatically send patches to upgrade recipes with this variable set during
>> +stable releases.
>> +
>> +.. note::
>> +
>> +   Patches to upgrade recipes without this variable may still be submitted
>> +   for stable branches, but the barrier for acceptance is high. The commit
>> +   message needs to justify that the version upgrade follows our stable
>> +   branch policy or that there is an exceptional reason for taking the
>> +   upgrade.
>> +
>> +A recipe may have :term:`UPSTREAM_STABLE_RELEASE_REGEX` set based on the
>> +following criteria:
>> +
>> +1. **Upstream stable branches exist** --- the upstream project maintains
>> +   branches named with a stable version component, and there is evidence
>> +   that these branches only collect bug-fix and security-fix changes
>> +   (no new features or ABI/API breakage). For example, util-linux version
>> +   ``2.41.3`` has three parts in its version and upstream has branches like
>> +   ``stable/v2.41`` with two parts. This demonstrates that bumps in the
>> +   third part (e.g. ``2.41.3`` to ``2.41.4``) are stable point releases.
>> +   Similarly, systemd maintains ``stable/v259-stable``.
>> +
>> +2. **Upstream maintainer confirmation** --- the upstream project's maintainer
>> +   explicitly confirms that a bump in a certain part of the version is
>> +   bug-fix only.
>> +
>> +3. **Clear historical or common-sense evidence** --- the project's change
>> +   history clearly shows that a certain class of version bump is bug-fix
>> +   only, or it is widely understood convention. For example, openssh's
>> +   ``p`` suffix increments (``10.2p1`` to ``10.2p2``) and kmod's patch-level
>> +   bumps are historically bug-fix only releases.
>> +
>> +.. note::
>> +
>> +   Patches to set :term:`UPSTREAM_STABLE_RELEASE_REGEX` are sent against the
>> +   master branch first and follow the normal review process. Once accepted on
>> +   master they may be backported to stable release branches. Exceptions may be
>> +   made when necessary, e.g. setting :term:`UPSTREAM_STABLE_RELEASE_REGEX` on
>> +   a stable branch for a recipe which has since been removed on master.
>> +
>> +How Stable Release Regexes Work
>> +-------------------------------
>> +
>> +The stable point upgrade mechanism uses a *filter regex* to constrain the
>> +upstream version check so that only versions within the same stable series
>> +are considered. When a recipe sets :term:`UPSTREAM_STABLE_RELEASE_REGEX`, the
>> +version-checking infrastructure in BitBake's fetchers (git, wget, crate)
>> +applies that regex to filter discovered upstream versions. Only versions
>> +matching the regex are considered as upgrade candidates.
>> +
>> +For example, if a recipe is currently at version ``1.4.2`` and the regex is
>> +``^1\.4(\.\d+)*$``, then version ``1.4.7`` would be a valid upgrade candidate
>> +but ``1.5.0`` would not.
>> +
>> +For recipes whose version uses a dot-separated scheme, the
>> +:ref:`ref-classes-upstream-stable-release-point` class can automatically
>> +generate this regex. For other versioning schemes, set
>> +:term:`UPSTREAM_STABLE_RELEASE_REGEX` directly in the recipe.
>> +
>> +
> Extra newline not needed here.

Thanks for reminding.

Regards,
Qi

>
>>   .. _ref-long-term-support-releases:
>>   
>>   Long Term Support Releases
>
> Antonin
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#9748): https://lists.yoctoproject.org/g/docs/message/9748
> Mute This Topic: https://lists.yoctoproject.org/mt/119829155/3618072
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [Qi.Chen@windriver.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>