Selecting a Yocto LTS Branch and Its Documentation

Hello again. You have already established that Yocto is a metadata-driven build system whose results depend on resolved inputs, task signatures, and controlled reuse. That makes the next decision foundational: which release line defines those inputs?

A Yocto release is not merely a version label. It determines the expected BitBake behavior, OpenEmbedded-Core metadata, Poky branch, documentation terminology, supported host assumptions, and compatibility expectations for additional layers. This lesson establishes a single, maintained baseline for the course and a disciplined way to consult documentation, release notes, and migration guidance without accidentally mixing release generations.

For this course, the selected baseline is:

Yocto Project 5.0, codename Scarthgap, using the scarthgap Poky branch and the 5.0 documentation set.

According to the supplied release-status snapshot, Scarthgap is an LTS series maintained through April 2028. We deliberately keep the entire course on this release line rather than mixing commands and metadata examples from newer development documentation or older tutorials.

---

Why release selection is an engineering decision

The Yocto Project releases on a regular cadence. Some releases have a relatively short stable-maintenance period, while designated Long Term Support releases receive maintenance for much longer. “Maintained” matters because security fixes, bug fixes, and compatible upstream stable updates may be backported to the branch.

An LTS designation does not mean “this branch never changes.” A maintained branch receives carefully controlled backports. It also does not mean “every layer works forever.” The project’s LTS policy covers:

• BitBake;
• OE-Core;
• meta-yocto;
• Yocto Project documentation.

It does not automatically cover a vendor BSP layer, an independently maintained application layer, or a community layer. Each external layer has its own lifecycle, branch policy, and compatibility claims. This will become especially important when you begin adding custom layers and BSP metadata.

The maintenance policy also emphasizes a master-first, backport-only approach. In practical terms, a security or bug fix is generally developed and accepted on the main development line before being considered for a stable or LTS branch. LTS maintenance therefore prioritizes correctness and compatibility over new features and broad upgrades.

That behavior is valuable in embedded work. A product team usually wants a predictable base where an update is more likely to be a focused fix than a surprise toolchain replacement or a major userspace redesign.

---

Selecting Scarthgap as the course baseline

The release table is the authoritative first stop for a release-selection decision. It tells you the codename, series number, support status, current point release, and expected end of support.

The supplied table identifies both Wrynose 6.0 and Scarthgap 5.0 as LTS releases. Why use Scarthgap rather than simply selecting the newest LTS?

For this course, Scarthgap is the deliberate choice because:

1. It is maintained LTS. The release table lists it as supported through April 2028.
2. It has a mature, stable documentation set. We can consistently use the 5.0 documentation throughout the course.
3. It is appropriate for QEMU-based learning. The course does not need a vendor BSP that could force a particular newer or older series.
4. It prevents accidental version mixing. Prior materials for this course already use 5.0 terminology and documentation.
5. It teaches a transferable industry practice. You will learn to freeze a coherent release line, then record exact revisions within it.

This is not a claim that Scarthgap is universally the best choice for every product. A real board-support package may require a different release because of vendor support, kernel needs, a certified toolchain, a required framework version, or a customer security policy. The correct decision process is:

Question	Why it matters
Is the series still maintained?	Determines availability of coordinated security and bug-fix maintenance
Does the selected BSP layer support it?	A physical board depends on compatible machine, kernel, bootloader, and device-tree metadata
Do required third-party layers support it?	An unsupported layer can block integration even when Poky itself is LTS
Does it support the required host environment?	Build-host compatibility is part of the release contract
Can the project commit to upgrading it before EOL?	LTS reduces upgrade frequency; it does not eliminate the need to plan upgrades

For our QEMU-focused environment, no vendor BSP constrains the choice. That lets us choose a maintained, coherent reference baseline rather than inheriting an old release because a hardware vendor never updated its layer.

---

A branch is a maintenance stream, not a permanent build identity

There is an important distinction between the release branch and an exact build baseline.

The scarthgap branch names the Scarthgap maintenance stream. It can receive approved updates during the LTS period. Therefore, two developers who check out scarthgap months apart may receive different commits even though they are on the same branch.

For learning and active maintenance, following the branch is useful: you receive the currently maintained state of the series. For a release build that must be reproduced months later, the branch name is insufficient. You must record an immutable Git commit.

Think of the relationship this way:

Item	Example	What it identifies
Release series	Yocto Project 5.0	A family of compatible releases and documentation
Codename	Scarthgap	The human-readable name for that series
Maintenance branch	scarthgap	A moving line receiving approved LTS updates
Point release	5.0.18 in the supplied snapshot	A published maintenance snapshot
Git commit	A full commit ID	The exact metadata source state used for one build

The branch answers: “Which supported release line am I using?”
The commit answers: “Exactly what metadata did this build use?”

This directly continues the reproducibility lesson. A build cannot be fully reconstructed from an instruction such as “use Scarthgap.” It needs the precise Poky commit, the exact commits of additional layers, local configuration, source revisions, and ideally the resulting manifests and build evidence.

Later, after cloning Poky, you will record the actual checkout using:

git branch --show-current
git rev-parse HEAD
git describe --tags --always

For now, do not clone or configure the build tree yet; the next lessons first establish the Ubuntu host prerequisites and workspace plan. What matters here is that you know what the clone must be aligned to:

Poky branch:          scarthgap
Yocto documentation:  5.0 / Scarthgap
Release notes:        5.0 / Scarthgap, plus the selected maintenance point
Migration guidance:   guidance whose destination is 5.0 / Scarthgap
External layers:      branches and commits compatible with Scarthgap

---

Use the documentation as a versioned interface

Yocto documentation has the same versioning problem as source code: documentation for a different release can be technically accurate yet wrong for your build.

A command or metadata fragment copied from:

• development documentation;
• a blog written for another release;
• an old tutorial;
• a vendor page using a different branch;

may use syntax, defaults, task behavior, variable names, supported host distributions, or layer conventions that do not match Scarthgap.

This is not a minor stylistic issue. In a metadata system, small syntax differences can change the final resolved datastore or cause an override to be ignored.

For this course, use the 5.0 documentation set as the default reference. When opening Yocto Project documentation, confirm that the version selector or page path identifies the 5.0 release rather than a development edition or another codename.

Use the three document types differently:

Document type	Primary purpose	When to read it
Reference and manuals	Explain variables, tasks, classes, commands, configuration, and supported workflows	Continuously, while implementing or diagnosing work
Release notes	Describe the scope, significant changes, known issues, and release-level information for the selected series or point release	Before adopting a new baseline and before updating it
Migration notes	Identify changes required when moving metadata or configuration from one release series to another	Before and during an upgrade from an earlier release

Release notes answer: “What changed in this release?”

Read the Scarthgap 5.0 release notes when you adopt the baseline. They help establish what is new or significant about the series, what changed from the prior release, and what limitations or important compatibility information might affect a build.

When maintaining a product, read the release information for the point release you plan to adopt as well. A point release normally represents accumulated maintenance rather than a new feature release, but it still changes your metadata baseline. Treat it as an engineering update: review it, test it, record it.

Migration notes answer: “What must I change to arrive here?”

Migration guidance is especially important when inheriting an older project. Suppose a project was built on an earlier release line. The correct approach is not to jump blindly to Scarthgap and fix errors one at a time. Instead:

1. Identify the project’s current Yocto series and all layer revisions.
2. Read the migration guidance for each release boundary crossed.
3. Update custom metadata in a controlled branch.
4. Build and test after each logical migration stage.
5. Record incompatibilities, replacements, and intentional policy changes.

As a beginner starting a clean course environment, you are not migrating a legacy build. Still, locate the migration document whose destination is 5.0 / Scarthgap and read its overview before importing recipes from tutorials or repositories. It gives you an early warning that metadata written for another series may need adaptation.

Manuals answer: “How does this release behave?”

The manuals are your implementation reference. When a lesson tells you to configure a variable, write a recipe, inspect a task, or use a BitBake command, look first in the 5.0 documentation.

A disciplined habit is to write the documentation version in your notes whenever behavior matters:

Observed behavior: BitBake task execution and metadata syntax
Documentation baseline: Yocto Project 5.0 / Scarthgap
Poky baseline: scarthgap branch, exact commit recorded separately

That note turns an isolated command into evidence someone else can evaluate.

---

The alignment rule for layers

A Yocto build is assembled from layers, but “it parses successfully” is not the same as “it is supported.”

When you add a layer later, verify all of the following:

• The layer declares compatibility with the Scarthgap series.
• You use the branch or release revision intended for Scarthgap.
• Its dependencies are present at compatible revisions.
• Its README and release notes do not require a different Poky series.
• Its license and maintenance status are acceptable for your project.

This prevents a common failure mode: pairing a modern Poky branch with an old layer because both happen to contain files named .bb and .bbappend. BitBake may report parse errors, subtly wrong recipe selection, incompatible patches, or failures much later in compilation.

Layer priority cannot rescue a release mismatch. Priority influences recipe selection in specific cases; it cannot make old APIs, outdated patches, incompatible task behavior, or unsupported dependencies become compatible. You will examine those mechanics in detail in the layers module.

For now, use this conservative rule:

Keep Poky, documentation, third-party layers, and project metadata on one explicitly recorded release line.

---

Create a release decision record

Create a small note outside any future build directory. This is not build output; it is project evidence. A simple file such as release-contract.md in a notes directory is sufficient.

Record the following content:

Course baseline
===============

Yocto Project series: 5.0
Codename: Scarthgap
Poky maintenance branch: scarthgap
Documentation baseline: Yocto Project 5.0 documentation
Support rationale: maintained LTS in the supplied release-status snapshot
Target approach: QEMU ARM, no vendor BSP required

Adoption rule:
- Record the exact Poky commit after cloning.
- Pin every added layer to an explicit compatible commit.
- Use release notes before accepting a point-release update.
- Consult migration notes before importing metadata from another release line.

Do not claim an exact commit yet: that becomes meaningful only after the clone is made. Once the environment exists, extend the file with:

• the full Poky commit ID;
• the output of git describe --tags --always;
• the date of the checkout;
• each added layer’s repository URL, branch, and commit;
• the selected image, machine, and distribution;
• a link or location for the resulting build manifest.

This small record is the beginning of a release handoff. It is also an excellent debugging tool. When a recipe behaves differently on another laptop or CI runner, the first question should be whether the two builds actually used the same release contract.

---

Takeaways and next step

You have selected Scarthgap, Yocto Project 5.0, as this course’s maintained LTS baseline. The corresponding Poky branch is scarthgap, and the matching reference material is the 5.0 documentation, release information, and migration guidance targeting 5.0.

The key distinctions are:

• An LTS series receives coordinated maintenance longer than a regular stable release, but it is not frozen forever.
• An LTS guarantee covers core Yocto Project components, not every vendor or community layer.
• A branch identifies a moving maintenance stream; an exact Git commit identifies a reproducible source baseline.
• Documentation, release notes, migration notes, Poky, and external layers must all be aligned to the same release series.
• Release selection is part of the build’s technical contract and must be recorded.

Next, you will prepare Ubuntu 22.04 as a Scarthgap build host: installing the required packages, validating locale and shell requirements, and checking the filesystem and Git setup before downloading the build system.