From 9aee15955ffc4c3b590aea5844d269d86e1107cb Mon Sep 17 00:00:00 2001 From: Kleber Sacilotto de Souza Date: Wed, 26 Nov 2025 15:07:56 +0100 Subject: [PATCH 1/5] docs: reference: add new page for kernel variants and branches Add a new page under /reference/ with a summary of the kernel variants and git branches. We have some definitions already, such as for HWE and OEM, which are linked on the new doc, but we were missing to put everything together as a starting point. Signed-off-by: Kleber Sacilotto de Souza --- docs/reference/index.md | 1 + docs/reference/ubuntu-kernels.md | 72 ++++++++++++++++++++++++++++++++ 2 files changed, 73 insertions(+) create mode 100644 docs/reference/ubuntu-kernels.md diff --git a/docs/reference/index.md b/docs/reference/index.md index 5edeb97..10d8b7f 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -15,6 +15,7 @@ more. :maxdepth: 1 :caption: Kernel variants +ubuntu-kernels hwe-kernels oem-kernels ``` diff --git a/docs/reference/ubuntu-kernels.md b/docs/reference/ubuntu-kernels.md new file mode 100644 index 0000000..94349bd --- /dev/null +++ b/docs/reference/ubuntu-kernels.md @@ -0,0 +1,72 @@ +# Ubuntu Kernel Variants and Branches + +Ubuntu maintains several kernel variants to balance the needs of stability, hardware enablement, and rapid development. This document outlines the primary kernel trees, their roles in the development lifecycle, and the git branching strategies used by the Canonical Kernel Team. + +For detailed technical references, please consult the {doc}`../index` and [Ubuntu kernels from Canonical](). + +## Ubuntu Development Kernels + +Ubuntu releases every 6 months; therefore, the Canonical Kernel Team constantly works on the active Ubuntu development series to integrate the latest Linux kernel features for the release. The development kernels serve as the testing ground for new features, upstream updates, and partner integration before they reach the stable releases. + +### The ``linux-unstable`` Tree + +The [linux-unstable tree]() represents the bleeding edge of Ubuntu kernel development. It is a fast-moving target designed to track the latest upstream Linux developments. + +* **Upstream Alignment:** It is usually rebased weekly against the latest upstream Release Candidate (``-rcX``) during the most active development period. New patches are also constantly applied to the branch. +* **Volatility:** Patchsets can be removed if problems are found. +* **Purpose:** It serves as the initial landing ground for upstream code and feature integration. It may still lack support for core components (e.g., AppArmor, NVIDIA drivers, ZFS, etc.); therefore, it is not guaranteed to have all features necessary to fully support an Ubuntu system. +* **Availability:** As it usually does not have all core components necessary to run a full Ubuntu user-space, it is available only via development PPAs and not in the Ubuntu archive. + +### The ``linux`` Tree + +Once a ``linux-unstable`` kernel version includes support for all core components and is deemed relatively stable, it is moved to the ``linux`` tree. + +* **Upstream Alignment:** Similar to the ``linux-unstable`` tree, it usually follows the latest upstream release. However, rebases are less frequent as some level of stability needs to be maintained. During a development cycle, it is expected to be updated to all ``major.minor`` upstream releases until the last version available before the Ubuntu release GA. +* **Purpose:** The ``linux`` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream ``major.minor`` version. + +### Ubuntu Kernel Next (UKN) + +Because the ``linux-unstable`` kernel moves too fast for larger integration work, the Canonical Kernel Team maintains the [Ubuntu Kernel Next]() tree, which is an integration tree designed to bridge the gap between the volatility of ``linux-unstable`` and the stability required for partner development. + +* **Workflow:** It is a periodic, read-only snapshot of ``linux-unstable``. +* **Integration:** It provides a stable codebase for integration work into the next development kernel. Integration issues (e.g., conflicts) can be spotted and fixed earlier. + +## Optimized Kernels + +In addition to the generic kernel, Canonical also provides optimized kernels which are derived from the generic kernel. For more information please consult [Ubuntu kernel variants from Canonical](). + +* **Purpose:** Kernels that have their configuration, hardware support, or additional features optimized for a variety of hardware platforms and workloads. Examples include kernels optimized for the Raspberry Pi ARM board (``linux-raspi``), for running as guests on the major public cloud providers, for IoT devices, etc. +* **Release and update cadence:** Optimized kernels are released and receive security updates with the same cadence as the Ubuntu generic kernel upon which they are based. + +### OEM Kernels + +OEM kernels are optimized derivatives designed specifically for Original Equipment Manufacturer (OEM) projects to support hardware pre-installed with Ubuntu. For more information please consult {doc}`oem-kernels`. + +* **Purpose:** They address unique timelines and hardware needs that may not align with the generic kernel release cadence and scope. +* **Staging Strategy:** OEM kernels often serve as a staging area. Modifications made here are intended to be merged into the generic Ubuntu kernel in subsequent releases. + +## Production and Enablement Kernels + +Once an Ubuntu version is released (General Availability), all kernels available in that release become production-ready and stable. They are maintained for the duration of the Ubuntu release support period and receive security updates and bug fixes via {doc}`Stable Release Updates (SRU) <../explanation/stable-release-updates>`. + +### HWE (Hardware Enablement) Kernels + +Hardware Enablement (HWE) kernels are available for Ubuntu Long Term Support (LTS) releases. They provide a way for LTS users to consume newer kernel versions and receive support for newer hardware (such as the graphics stack). For more information please consult {doc}`hwe-kernels`. + +* **Rolling Release:** HWE kernels are "rolling" in nature; they are typically backported from subsequent interim or LTS Ubuntu releases to the previous LTS. +* **Lifecycle:** HWE kernels are supported until the next HWE stack is released, at which point users are encouraged to upgrade to the newer version. + +## Git Branching Strategy + +When working with Ubuntu kernel repositories, you will primarily interact with two key branches. + +### ``master`` branch + +The ``master`` branch represents the current state of the kernel source as it exists in the ``-updates`` pocket of the Ubuntu archive. It contains the linear history of all the stable releases published for that kernel. + +### ``master-next`` branch + +The ``master-next`` branch serves as the staging area for the **next** Stable Release Update (SRU). + +* **Purpose:** Commits intended for the next update are applied here first after being reviewed and acknowledged by the Canonical Kernel Team. This branch will also contain commits for the kernel builds that are published for testing in the ``-proposed`` pocket of the Ubuntu archive. +* **Flow:** Patches land in ``master-next`` for integration and testing before being promoted to ``master`` after the kernel SRU update is published to ``-updates``. From 9e7d31ebacd8c54e79c28b6dd27a87ffebc18421 Mon Sep 17 00:00:00 2001 From: AnneCYH Date: Fri, 5 Dec 2025 13:20:13 +0800 Subject: [PATCH 2/5] doc: minor edits Signed-off-by: AnneCYH --- docs/reference/ubuntu-kernels.md | 94 +++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 32 deletions(-) diff --git a/docs/reference/ubuntu-kernels.md b/docs/reference/ubuntu-kernels.md index 94349bd..277f439 100644 --- a/docs/reference/ubuntu-kernels.md +++ b/docs/reference/ubuntu-kernels.md @@ -1,72 +1,102 @@ -# Ubuntu Kernel Variants and Branches +(ref-ubuntu-kernel-variants-branches)= -Ubuntu maintains several kernel variants to balance the needs of stability, hardware enablement, and rapid development. This document outlines the primary kernel trees, their roles in the development lifecycle, and the git branching strategies used by the Canonical Kernel Team. +# Ubuntu kernel variants and branches -For detailed technical references, please consult the {doc}`../index` and [Ubuntu kernels from Canonical](). +Ubuntu maintains several kernel variants to balance the needs of stability, hardware enablement, and rapid development. +This document outlines the primary kernel trees, their roles in the development lifecycle, and the git branching strategies used by the Canonical Kernel Team. -## Ubuntu Development Kernels +```{seealso} +- See the list of {doc}`reference topics ` for more technical details. +- See the [Ubuntu kernels from Canonical](https://ubuntu.com/kernel) for general information about Ubuntu Linux kernels. +``` -Ubuntu releases every 6 months; therefore, the Canonical Kernel Team constantly works on the active Ubuntu development series to integrate the latest Linux kernel features for the release. The development kernels serve as the testing ground for new features, upstream updates, and partner integration before they reach the stable releases. +## Ubuntu development kernels -### The ``linux-unstable`` Tree +Ubuntu releases every 6 months; therefore, the Canonical Kernel Team constantly works on the active Ubuntu development series to integrate the latest Linux kernel features for the release. +The development kernels serve as the testing ground for new features, upstream updates, and partner integration before they reach the stable releases. -The [linux-unstable tree]() represents the bleeding edge of Ubuntu kernel development. It is a fast-moving target designed to track the latest upstream Linux developments. +### The `linux-unstable` tree -* **Upstream Alignment:** It is usually rebased weekly against the latest upstream Release Candidate (``-rcX``) during the most active development period. New patches are also constantly applied to the branch. +The [linux-unstable tree]() represents the bleeding edge of Ubuntu kernel development. +It is a fast-moving target designed to track the latest upstream Linux developments. + +* **Upstream alignment:** It is usually rebased weekly against the latest upstream Release Candidate (`-rcX`) during the most active development period. + New patches are also constantly applied to the upstream branch. * **Volatility:** Patchsets can be removed if problems are found. -* **Purpose:** It serves as the initial landing ground for upstream code and feature integration. It may still lack support for core components (e.g., AppArmor, NVIDIA drivers, ZFS, etc.); therefore, it is not guaranteed to have all features necessary to fully support an Ubuntu system. +* **Purpose:** It serves as the initial landing ground for upstream code and feature integration. + It may still lack support for core components (e.g., AppArmor, NVIDIA drivers, ZFS, etc.) and is not guaranteed to have all features necessary to fully support an Ubuntu system. * **Availability:** As it usually does not have all core components necessary to run a full Ubuntu user-space, it is available only via development PPAs and not in the Ubuntu archive. -### The ``linux`` Tree +### The `linux` tree -Once a ``linux-unstable`` kernel version includes support for all core components and is deemed relatively stable, it is moved to the ``linux`` tree. +Once a `linux-unstable` kernel version includes support for all core components and is deemed relatively stable, it is moved to the `linux` tree. -* **Upstream Alignment:** Similar to the ``linux-unstable`` tree, it usually follows the latest upstream release. However, rebases are less frequent as some level of stability needs to be maintained. During a development cycle, it is expected to be updated to all ``major.minor`` upstream releases until the last version available before the Ubuntu release GA. -* **Purpose:** The ``linux`` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream ``major.minor`` version. +* **Upstream alignment:** Similar to the `linux-unstable` tree, it usually follows the latest upstream release. + However, rebases are less frequent as some level of stability needs to be maintained. + During a development cycle, it is expected to be updated to all `major.minor` upstream releases until the last version available before the Ubuntu release GA. +* **Purpose:** The `linux` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream `major.minor` version. ### Ubuntu Kernel Next (UKN) -Because the ``linux-unstable`` kernel moves too fast for larger integration work, the Canonical Kernel Team maintains the [Ubuntu Kernel Next]() tree, which is an integration tree designed to bridge the gap between the volatility of ``linux-unstable`` and the stability required for partner development. +Because the `linux-unstable` kernel moves too fast for larger integration work, the Canonical Kernel Team maintains the [Ubuntu Kernel Next]() tree. +UKN integration tree designed to bridge the gap between the volatility of `linux-unstable` and the stability required for partner development. + +* **Workflow:** It is a periodic, read-only snapshot of `linux-unstable`. +* **Integration:** It provides a stable code base for integration work into the next development kernel. + Integration issues (e.g., conflicts) can be spotted and fixed earlier. -* **Workflow:** It is a periodic, read-only snapshot of ``linux-unstable``. -* **Integration:** It provides a stable codebase for integration work into the next development kernel. Integration issues (e.g., conflicts) can be spotted and fixed earlier. +## Optimized kernels -## Optimized Kernels +In addition to the generic kernel, Canonical also provides optimized kernels which are derived from the generic kernel. -In addition to the generic kernel, Canonical also provides optimized kernels which are derived from the generic kernel. For more information please consult [Ubuntu kernel variants from Canonical](). +```{seealso} +- [Ubuntu kernel variants from Canonical]() +``` -* **Purpose:** Kernels that have their configuration, hardware support, or additional features optimized for a variety of hardware platforms and workloads. Examples include kernels optimized for the Raspberry Pi ARM board (``linux-raspi``), for running as guests on the major public cloud providers, for IoT devices, etc. +* **Purpose:** Kernels that have their configuration, hardware support, or additional features optimized for a variety of hardware platforms and workloads. Examples include kernels optimized for the Raspberry Pi ARM board (`linux-raspi`), for running as guests on the major public cloud providers, for IoT devices, etc. * **Release and update cadence:** Optimized kernels are released and receive security updates with the same cadence as the Ubuntu generic kernel upon which they are based. ### OEM Kernels -OEM kernels are optimized derivatives designed specifically for Original Equipment Manufacturer (OEM) projects to support hardware pre-installed with Ubuntu. For more information please consult {doc}`oem-kernels`. +OEM kernels are optimized derivatives designed specifically for Original Equipment Manufacturer (OEM) projects to support hardware pre-installed with Ubuntu. + +```{seealso} +- {doc}`oem-kernels` +``` * **Purpose:** They address unique timelines and hardware needs that may not align with the generic kernel release cadence and scope. -* **Staging Strategy:** OEM kernels often serve as a staging area. Modifications made here are intended to be merged into the generic Ubuntu kernel in subsequent releases. +* **Staging strategy:** OEM kernels often serve as a staging area. Modifications made here are intended to be merged into the generic Ubuntu kernel in subsequent releases. -## Production and Enablement Kernels +## Production and enablement kernels -Once an Ubuntu version is released (General Availability), all kernels available in that release become production-ready and stable. They are maintained for the duration of the Ubuntu release support period and receive security updates and bug fixes via {doc}`Stable Release Updates (SRU) <../explanation/stable-release-updates>`. +Once an Ubuntu version is released to General Availability (GA), all kernels available in that release become production-ready and stable. +They are maintained for the duration of the Ubuntu release support period and receive security updates and bug fixes via {doc}`Stable Release Updates (SRU) `. ### HWE (Hardware Enablement) Kernels -Hardware Enablement (HWE) kernels are available for Ubuntu Long Term Support (LTS) releases. They provide a way for LTS users to consume newer kernel versions and receive support for newer hardware (such as the graphics stack). For more information please consult {doc}`hwe-kernels`. +Hardware Enablement (HWE) kernels are available for Ubuntu Long Term Support (LTS) releases. +They provide a way for LTS users to consume newer kernel versions and receive support for newer hardware (such as the graphics stack). + +```{seealso} +- {doc}`hwe-kernels` +``` -* **Rolling Release:** HWE kernels are "rolling" in nature; they are typically backported from subsequent interim or LTS Ubuntu releases to the previous LTS. +* **Rolling release:** HWE kernels are "rolling" in nature; they are typically backported from subsequent interim or LTS Ubuntu releases to the previous LTS. * **Lifecycle:** HWE kernels are supported until the next HWE stack is released, at which point users are encouraged to upgrade to the newer version. -## Git Branching Strategy +## Git branching strategy When working with Ubuntu kernel repositories, you will primarily interact with two key branches. -### ``master`` branch +### `master` branch -The ``master`` branch represents the current state of the kernel source as it exists in the ``-updates`` pocket of the Ubuntu archive. It contains the linear history of all the stable releases published for that kernel. +The `master` branch represents the current state of the kernel source as it exists in the `-updates` pocket of the Ubuntu archive. +It contains the linear history of all the stable releases published for that kernel. -### ``master-next`` branch +### `master-next` branch -The ``master-next`` branch serves as the staging area for the **next** Stable Release Update (SRU). +The `master-next` branch serves as the staging area for the **next** Stable Release Update (SRU). -* **Purpose:** Commits intended for the next update are applied here first after being reviewed and acknowledged by the Canonical Kernel Team. This branch will also contain commits for the kernel builds that are published for testing in the ``-proposed`` pocket of the Ubuntu archive. -* **Flow:** Patches land in ``master-next`` for integration and testing before being promoted to ``master`` after the kernel SRU update is published to ``-updates``. +* **Purpose:** Commits intended for the next update are applied here first after being reviewed and acknowledged by the Canonical Kernel Team. + This branch will also contain commits for the kernel builds that are published for testing in the `-proposed` pocket of the Ubuntu archive. +* **Flow:** Patches land in `master-next` for integration and testing before being promoted to `master` after the kernel SRU update is published to `-updates`. From 249a79b8bce9af138761e402f61b35829f292dbb Mon Sep 17 00:00:00 2001 From: Kleber Sacilotto de Souza Date: Tue, 16 Dec 2025 21:02:43 +0100 Subject: [PATCH 3/5] docs: reference: ubuntu-kernels: add summary table Add a table summarising the difference between the development kernels. Also reorder some of the kernels to keep them in a logical order, following from the most unstable to the most stable one. Signed-off-by: Kleber Sacilotto de Souza --- docs/reference/ubuntu-kernels.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/reference/ubuntu-kernels.md b/docs/reference/ubuntu-kernels.md index 277f439..27694ef 100644 --- a/docs/reference/ubuntu-kernels.md +++ b/docs/reference/ubuntu-kernels.md @@ -15,6 +15,14 @@ This document outlines the primary kernel trees, their roles in the development Ubuntu releases every 6 months; therefore, the Canonical Kernel Team constantly works on the active Ubuntu development series to integrate the latest Linux kernel features for the release. The development kernels serve as the testing ground for new features, upstream updates, and partner integration before they reach the stable releases. +The following table summarizes the main Ubuntu development kernels: + +| Kernel Tree | Purpose | Stability | Upstream Tracking | Notes | +|--------------------|-----------------------------------------|---------------------|------------------------------------|------------------------------------------------| +| **linux-unstable** | Early integration & testing | Highly volatile | Tracks upstream RCs (frequent rebases) | Lack full Ubuntu integration (AppArmor, NVIDIA, ZFS, etc.) | +| **Ubuntu Kernel Next** | Stable snapshot for integration work | Moderately stable | Snapshot of `linux-unstable` | Read-only; used for partner/integration testing | +| **linux** | Ubuntu kernel | Relatively stable | Tracks upstream stable releases | Becomes the GA kernel for the Ubuntu release | + ### The `linux-unstable` tree The [linux-unstable tree]() represents the bleeding edge of Ubuntu kernel development. @@ -27,15 +35,6 @@ It is a fast-moving target designed to track the latest upstream Linux developme It may still lack support for core components (e.g., AppArmor, NVIDIA drivers, ZFS, etc.) and is not guaranteed to have all features necessary to fully support an Ubuntu system. * **Availability:** As it usually does not have all core components necessary to run a full Ubuntu user-space, it is available only via development PPAs and not in the Ubuntu archive. -### The `linux` tree - -Once a `linux-unstable` kernel version includes support for all core components and is deemed relatively stable, it is moved to the `linux` tree. - -* **Upstream alignment:** Similar to the `linux-unstable` tree, it usually follows the latest upstream release. - However, rebases are less frequent as some level of stability needs to be maintained. - During a development cycle, it is expected to be updated to all `major.minor` upstream releases until the last version available before the Ubuntu release GA. -* **Purpose:** The `linux` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream `major.minor` version. - ### Ubuntu Kernel Next (UKN) Because the `linux-unstable` kernel moves too fast for larger integration work, the Canonical Kernel Team maintains the [Ubuntu Kernel Next]() tree. @@ -45,6 +44,15 @@ UKN integration tree designed to bridge the gap between the volatility of `linux * **Integration:** It provides a stable code base for integration work into the next development kernel. Integration issues (e.g., conflicts) can be spotted and fixed earlier. +### The `linux` tree + +Once a `linux-unstable` kernel version includes support for all core components and is deemed relatively stable, it is moved to the `linux` tree. + +* **Upstream alignment:** Similar to the `linux-unstable` tree, it usually follows the latest upstream release. + However, rebases are less frequent as some level of stability needs to be maintained. + During a development cycle, it is expected to be updated to all `major.minor` upstream releases until the last version available before the Ubuntu release GA. +* **Purpose:** The `linux` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream `major.minor` version. + ## Optimized kernels In addition to the generic kernel, Canonical also provides optimized kernels which are derived from the generic kernel. From a7ee7f45e05c02e377272c0f7f4bee813260a775 Mon Sep 17 00:00:00 2001 From: Kleber Sacilotto de Souza Date: Tue, 16 Dec 2025 21:05:07 +0100 Subject: [PATCH 4/5] docs: reference: ubuntu-kernels: add mention to main branches Some Ubuntu kernel trees are using main/main-next branches instead of master/master-next. Update the branches description to include main* as well. Signed-off-by: Kleber Sacilotto de Souza --- docs/reference/ubuntu-kernels.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference/ubuntu-kernels.md b/docs/reference/ubuntu-kernels.md index 27694ef..66e986d 100644 --- a/docs/reference/ubuntu-kernels.md +++ b/docs/reference/ubuntu-kernels.md @@ -96,15 +96,15 @@ They provide a way for LTS users to consume newer kernel versions and receive su When working with Ubuntu kernel repositories, you will primarily interact with two key branches. -### `master` branch +### `master-next`/`main-next` branches -The `master` branch represents the current state of the kernel source as it exists in the `-updates` pocket of the Ubuntu archive. -It contains the linear history of all the stable releases published for that kernel. - -### `master-next` branch - -The `master-next` branch serves as the staging area for the **next** Stable Release Update (SRU). +The `master-next` or `main-next` branches serve as the staging area for the **next** Stable Release Update (SRU). * **Purpose:** Commits intended for the next update are applied here first after being reviewed and acknowledged by the Canonical Kernel Team. This branch will also contain commits for the kernel builds that are published for testing in the `-proposed` pocket of the Ubuntu archive. * **Flow:** Patches land in `master-next` for integration and testing before being promoted to `master` after the kernel SRU update is published to `-updates`. + +### `master`/`main` branches + +The `master` or `main` branches represent the current state of the kernel source as it exists in the `-updates` pocket of the Ubuntu archive. +It contains the linear history of all the stable releases published for that kernel. From 8ef4a6fea53bde309de387ce93e3db637ae5b286 Mon Sep 17 00:00:00 2001 From: Kleber Sacilotto de Souza Date: Tue, 16 Dec 2025 21:11:14 +0100 Subject: [PATCH 5/5] docs: fixed spellcheck linkcheck errors (#84) Signed-off-by: Kleber Sacilotto de Souza --- docs/.custom_wordlist.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index fd9119b..8d65109 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,6 +1,7 @@ ack'd ACKs +AppArmor backport backported enablement @@ -11,9 +12,15 @@ master metapackage packageset patchset +patchsets PPAs +RCs +rebased +rebases respin respins selftests subtree unported +UKN +ZFS