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.

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 initially for two years
• 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:

• Branches only have community support status if there is an active community member willing to step into the maintainer role for that series
• 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 artefacts
• Master first policy recommended

EOL (End of life):

• When there is no longer any active community maintainer, branches become EOL

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. These would be thin specific purpose layers which can be stacked with an LTS release to mix a specific feature into that build. These are to be created on an as needed basis and maintained by the people who need them. The structure would be to create them in the repository oecore-backport-mixin 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.

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

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

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 table above.

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

Maintainer Procedures

Merge cycle

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

1. Look out for patches on the mailing list marked with the stable 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. Test the branch 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.
6. Split out any bitbake changes and send them to the bitbake-devel mailing list (marking them with the appropriate stable version in the subject line e.g. [1.20])
7. Split out OE-Core changes and create an openembedded-core-contrib branch containing them; send the cover letter only (marking it as such in the subject) to the openembedded-core mailing list.
8. Split out any meta-yocto changes and create a poky-contrib branch containing them; send the cover letter only (marking it as such in the subject) to the poky mailing list.
9. When the patches are merged, mark any bugs specific to the stable branch as resolved as appropriate.

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

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. Send a patch to update the stable version in meta-yocto/conf/distro/poky.conf for the release
2. Once that is merged, ask Richard to run the release candidate build
   • The stable branch maintainer should monitor the build and follow up on any failures
3. When the release candidate build completes successfully, TBD 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 to so she can incorporate them in final release notes and to Stephen Jolley <sjolley.yp.pm@gmail.com> so he can have them in preparation for the release meeting.

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 <stephen.k.jolley@intel.com> and he will present it.

Kernel LTS

Kernel cadence

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.