diff mbox series

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

Message ID 20260615062438.3119651-3-Qi.Chen@windriver.com
State New
Headers show
Series [1/3] ref-manual/classes.rst: add upstream-stable-release-point class documentation | expand

Commit Message

ChenQi June 15, 2026, 6:24 a.m. UTC 
From: Chen Qi <Qi.Chen@windriver.com>

Move the Stable/LTS Patch Acceptance Policies from the wiki into the
reference manual. Expand the 'potentially acceptable: bug-fix-only
version upgrades' item with a new section documenting:
- criteria for qualifying upstreams (stable branches, maintainer
  confirmation, historical evidence)
- how stable release regexes work to constrain version checks

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

Comments

Paul Barker June 15, 2026, 9:01 a.m. UTC | #1 
On Sun, 2026-06-14 at 23:24 -0700, Chen Qi via lists.yoctoproject.org
wrote:
> From: Chen Qi <Qi.Chen@windriver.com>
> 
> Move the Stable/LTS Patch Acceptance Policies from the wiki into the
> reference manual. Expand the 'potentially acceptable: bug-fix-only
> version upgrades' item with a new section documenting:
> - criteria for qualifying upstreams (stable branches, maintainer
>   confirmation, historical evidence)
> - how stable release regexes work to constrain version checks
> 
> Signed-off-by: Chen Qi <Qi.Chen@windriver.com>

Hi Qi,

Firstly, thank you for sending this! I really appreciate the effort to
help migrate wiki content into the docs.

> ---
>  documentation/ref-manual/release-process.rst | 97 ++++++++++++++++++++
>  1 file changed, 97 insertions(+)
> 
> diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
> index a55187c14..3bccbfbdb 100644
> --- a/documentation/ref-manual/release-process.rst
> +++ b/documentation/ref-manual/release-process.rst
> @@ -127,6 +127,103 @@ 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
> +-  Changes to follow an upstream stable series or LTS that aligns with
> +   the original release (based on compatibility)

I would probably say "Version updates which follow..." instead of
"Changes to follow...". "Changes" sounds a little too broad.

> +
> +**Potentially acceptable:**
> +
> +-  Fixes so the codebase works with newly released distros (only in the
> +   first six months after a given release series first release)

We have actually been accepting updates to support new distros based on
complexity of the patches and risk of regressions, not on the age of the
stable branch. So, I think we can drop the statement in brackets - these
changes are potentially acceptable but subject to maintainer judgement.

> +-  Bug-fix-only version upgrades for upstreams that meet the criteria for
> +   stable point release tracking (see
> +   :ref:`ref-manual/release-process:stable point release upgrades`)

This duplicates what we have in the acceptable section above. I think
once an UPSTREAM_STABLE_RELEASE_REGEX patch has been backported, version
updates following the accepted pattern should be considered acceptable
by default (with the usual ability to reject if upstream fails to follow
their own stable guidelines).

> +
> +**Unacceptable:**
> +
> +-  General version upgrades
> +-  New features
> +-  ABI/API breakage

I would add "Metadata improvements and refactoring, unless this is a
dependency of a required fix".

> +
> +.. _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
> +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
> +"potentially acceptable: bug-fix-only version upgrades" 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
> +automatically upgrade recipes with this variable set during stable releases.

The AUH sends patches instead of directly merging changes, so I'd reword
this a little:

"...will then automatically send patches to upgrade recipes..."

> +
> +.. note::
> +
> +   Recipes without this variable can still be upgraded for stable releases
> +   through manual review. They simply will not be picked up automatically
> +   by AUH.

This makes it sound like such updates are likely to be accepted, which
isn't really true. So, perhaps:

"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 if any of the
> +following criteria are met:

I would say "...based on the following criteria:" as there is still
maintainer judgement involved and we may not automatically accept things
that seem to meet the 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.

I think we need to note the process that patches to set
UPSTREAM_STABLE_RELEASE_REGEX are sent against the master branch first
and follow our normal review process. Once accepted on master they may
be backported to stable release branches. Exceptions may be made when
necessary, e.g. setting 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.
> +
> +
>  .. _ref-long-term-support-releases:

Best regards,
diff mbox series

Patch

diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst
index a55187c14..3bccbfbdb 100644
--- a/documentation/ref-manual/release-process.rst
+++ b/documentation/ref-manual/release-process.rst
@@ -127,6 +127,103 @@  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
+-  Changes to follow an upstream stable series or LTS that aligns with
+   the original release (based on compatibility)
+
+**Potentially acceptable:**
+
+-  Fixes so the codebase works with newly released distros (only in the
+   first six months after a given release series first release)
+-  Bug-fix-only version upgrades for upstreams that meet the criteria for
+   stable point release tracking (see
+   :ref:`ref-manual/release-process:stable point release upgrades`)
+
+**Unacceptable:**
+
+-  General version upgrades
+-  New features
+-  ABI/API breakage
+
+.. _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
+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
+"potentially acceptable: bug-fix-only version upgrades" 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
+automatically upgrade recipes with this variable set during stable releases.
+
+.. note::
+
+   Recipes without this variable can still be upgraded for stable releases
+   through manual review. They simply will not be picked up automatically
+   by AUH.
+
+A recipe may have :term:`UPSTREAM_STABLE_RELEASE_REGEX` set if any of the
+following criteria are met:
+
+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.
+
+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.
+
+
 .. _ref-long-term-support-releases:
 
 Long Term Support Releases