Stable Release and LTS

Yocto Project Stable Branch Maintenance and Long Term Support (LTS)

Background on how the project's LTS plans came about can be found here. The document below details the current project release lifecycle and LTS plans. The aim is to have a stable series maintenance policy which allows for different stages of maintenance including standard "stable" series, LTS series and community support.

Current Maintainers list

Release Lifecycle

The project releases every six months in April and October (spring and fall). This is necessary to bring development together to a focus point and provide points of increased testing and focus on stability. There are two possible lifecycles a release may follow:

Initial Release -> Stable -> Community -> EOL

or

Initial Release -> LTS -> Community -> EOL

The change in status of a given release series should be announced in the weekly status report and reflected on the “Releases” wiki page.

The stages have the following properties:

Stable/LTS common properties:

• Has point release tarballs created
• Has release artefacts
• Patches merged to the main repository branch
• Requires autobuilder testing
• The project will appoint someone to act as the maintainer to coordinate and handle patch testing and merging
• Strict “backport only”, master first policy

Stable/LTS differences:

• Stable releases are maintained for seven months
• LTS releases are maintained for four years (as of June 2023, announced here)
• LTS releases are preannounced and known to be LTS in advance (usually every two years)
• LTS tested only on a subset of supported native build platforms (announced at time of LTS)

Community status properties:

• A branch transitions to community support after the last stable dot release identified by the stable/LTS maintainer.
• A call for a community support maintainer is sent to the mailing lists.
  • A six (6) week waiting period.
  • if there is no new maintainer, then the branch goes to into EOL status
• Branches only have community support status if there is an active community member willing to step into the maintainer role for that series
• All the same repos are covered as in Stable
• Follows the same the Stable processes, except;
  • Patches merge to the main repository but in a community/XXX namespace
  • Automated testing is on a best effort basis, some autobuilder cycles may be available but not guaranteed.
  • The maintainer is required to publish a testing plan to show what testing will be made for patches to merge to the community branch.
  • No point releases version and no release artifacts
• Master first policy recommended

EOL (End of life):

• No community support maintainer after the six (6) week waiting period
• When there is no longer any active community maintainer, branches become EOL
  • No new changes for 2 months
• Artifacts will be removed for EOL older than????
  • process under development

LTS “Mixin” repositories

We realise that a given LTS may need other versions of some components within its lifetime as no “one size” fits everyone’s needs. Rather than adding potentially invasive changes to older releases (such as new gcc versions), the project proposes the use of “mixin” layers (see https://docs.yoctoproject.org/dev//ref-manual/release-process.html#stable-release-process).

The structure would be to create them in the repository meta-lts-mixins with the branch naming scheme <releaseseries>/<mixin name>. We expect this may be used for gcc and possibly for rapidly changing languages like go/nodejs/rust. Policies on testing these layers will depend on how widespread their usage is and determined on a case by case basis. There may be other 'mixin' layers within the wider community too. Access to the repository branches can be granted by the Yocto Project TSC upon application.

The layers should have a single purpose and be Yocto Project Compatible (passing the test script) allowing them to be selected by users as needed. The maintainer should be listed in the README and note when the layer is no longer maintained.

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” seven month support window.

Patches must pass testing on the project’s automated test infrastructure.

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 codebase works with newly released distros (only in the first six months after a given release series first releases)
• Bug fix only version upgrades for upstreams with a good stable process

Unacceptable:

• General version upgrades
• New features
• ABI/API breakage

Components (layers) to be covered

The project LTS covers:

• Bitbake
• OE-Core
• Meta-yocto
• yocto-docs

The project LTS does not cover:

• meta-mingw
• meta-gplv2
• vendor layers

Other layers can and will have their own LTS processes.

Testing

The project releases are only tested using the automated testing based on virtual environments. The build host OSes used to run these tests are determined at the initial release time. For LTS releases only some subset of native OSes maybe supported, particularly where the lifetime of the OS would be shorter than the LTS.

Further testing of releases, e.g. on real hardware platforms is encouraged and there is a process to allow these results to be merged into the release test results but the process for making the release no longer depends upon this happening.

Process ( TOC)

• Need to document the following processes:
  • How maintainer is selected
  • How are patches proposed - Done
  • How are patches queued/tested/reviewed/merged - Done
  • When are point releases made? - Done
  • How to trigger and run a point release - Done
  • Release process itself
  • Transferring stable/LTS release to community/EOL status - YP TSC
  • New maintainer training - TBD

Requesting a fix in a stable branch

With reference to the above policies, if you would like to request a backport of a commit in a newer release, you can either (a) do the backport yourself and send the patch marked with [branchname] to the appropriate mailing list; or alternatively (b) you can send a simple request giving commit hashes / URLs that you would like to be backported. In both cases it helps to CC the maintainer - refer to the stable release table.

For information on which mailing list you should send these to see the README file in the Poky repository.

Maintainer Procedures

Normal process

When there are enough changes (or a few critical ones), the stable/LTS maintainer should follow this procedure:

1. Look out for patches on the mailing list marked with the appropriate branch name in the subject
2. Look through recently merged patches in master that are suitable for backporting
3. Collect patches together on a branch
   • If a submitted patch is a backport from master, rather than taking the patch as submitted, it is preferable to backport the patch from master so that the original commit message is preserved.
   • If you do the backporting from poky you will get the original commit ID in the commit message which is useful for reference.
   • It is beneficial to change the original commit ID line to say "OE-Core master rev" instead of "OE-Core rev" to distinguish it from the OE-Core branch revision that will be added when the commit is merged
4. Run a local build or two to pick up any obvious problems
5. Bitbake change should be in the bitbake-contrib repo
   1. https://git.openembedded.org/bitbake-contrib stable/{branch}-nut
6. Openembedded-core changes should be be in the openembedded-core-contrib stable/{branch}-nut
   1. https://git.openembedded.org/openembedded-core-contrib
7. Meta-yocto changes should be in poky-contrib meta-yocto/stable/{branch}-nut
   1. git://git.yoctoproject.org/poky-contrib
8. yocto-docs changes should be in poky-contrib yocto-docs/stable/{branch}-nut
   1. git://git.yoctoproject.org/poky-contrib
9. Now create your Poky distro for testing.
   1. The Autobuilder requires changes to reside in poky, bitbake and openembedded-core
   2. Combine bitabke, core, meta-yocto and yocto-docs changes into one repo.
   3. Push the changes to poky-contrib stable/{branch}-nut
   4. git://git.yoctoproject.org/poky-contrib
10. Test the changes on the autobuilder (see How to start a build on the Autobuilder)
    • Make sure you check directly for the results of the build as these won't be reported to the yocto-builds mailing list.
    1. For any build failure, Defects should be opened
    2. Address any build failures, update repo's accordingly and rebuild

There will very likely be a number of these cycles during the lifetime of the stable branch.

Patch review

1. When collating patches for review, Make sure of the following:
   1. Subject indicates "Patch review"
   2. Provide a deadline for any comments included in the body of the email
   3. Standard to date is 2 days.
      1. Exception is if the changes are patches sent to the appropriate mailing list.
   4. Use the appropriate branch reference.
   5. Use create-pull-request -p "{branch}" ...{etc}
2. Send any bitbake changes bitbake-devel mailing list
3. Send any OE-Core changes openembedded-core mailing list.
4. Send any meta-yocto changes to the poky@lists.yoctoproject.org mailing list.
5. Send any yocto-docs changes the docs@lists.yoctoproject.org mailing list.
6. Wait for any feedback
   1. If there are changes make any necessary adjustments
      1. rebuild if necessary
7. Push any changes to the appropriate repos and branches.

Merge request

1. Push affected repos and branches to stable/{branch}-next branch
2. When preparing patches for merge, Make sure of the following:
   1. Subject indicates "Merge Request"
   2. Use the appropriate branch reference.
   3. Use create-pull-requests -p"{branch}"
3. Send any bitbake changes bitbake-devel mailing list
4. Send any OE-Core changes openembedded-core mailing list.
5. Send any meta-yocto changes to the poky@lists.yoctoproject.org mailing list.
6. Send any yocto-docs changes the docs@lists.yoctoproject.org mailing list.
7. When the patches are merged, mark any bugs specific to the stable branch as resolved as appropriate

Point release

Normally point releases are scheduled in advance as appropriate - contact Stephen Jolley <sjolley.yp.pm@gmail.com> and CC: Ricard Purdie <richard.purdie@linuxfoundation.org> about scheduling point releases.

1. Update yocto-docs with release information.
   1. Send a patch to docs@lists.yoctoproject.org
2. Once all dot release changes are merged, ask Richard to run the release candidate build
   • The stable branch or LTS maintainer should monitor the build and follow up on any failures
3. When the release candidate build completes successfully, The stable branch or LTS maintainer should notify the QA team to start the release QA process.
4. Gather together changes in the form needed for a release notes and send them Yocto Project TSC, Branch or LTS maintainer for review and approval.
   1. If acceptable the changes will be incorporated into the final release notes and to Stephen Jolley <sjolley.yp.pm@gmail.com> so he can have them in preparation for the release meeting.
5. Send a patch to update the stable version in meta-yocto/conf/distro/poky.conf for the release

Other

• It is useful to provide status updates on the Yocto Project technical call, particularly coming up to a stable release. If you're not able to be on the call, send the status update information to Stephen Jolley <sjolley.yp.pm@gmail.com> and he will present it.

Releases

Yocto Project releases

Kernel LTS

Kernel cadence

New Releases process

Standard release process

Decision Makers

Decisions are expected to be handled by the maintainers. The TSC holds the ultimate decision making authority in case of disagreement. The TSC makes the final release go/nogo decisions.