From 18a88410a1a1c0246416e3eeabe731cf9b1d123c Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Tue, 7 Apr 2026 15:40:22 +0200 Subject: [PATCH 1/4] docs: move to Diataxis structure Signed-off-by: Eike Waldt On-behalf-of: SAP --- .github/workflows/build.yml | 2 + README.md | 77 +------------------------------- docs/reference/README.md | 88 +++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 76 deletions(-) mode change 100644 => 120000 README.md create mode 100644 docs/reference/README.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bea3741..706655f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,6 +1,8 @@ name: Build Kernel on: push: + paths-ignore: + - 'docs/**' workflow_dispatch: schedule: - cron: '0 0 * * *' diff --git a/README.md b/README.md deleted file mode 100644 index f898513..0000000 --- a/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# Kernel builds for Garden Linux - -This repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. -The build is based on [the debian kernel build](https://salsa.debian.org/kernel-team/linux). - -Garden Linux includes the latest LTS version of the kernel. - -## Components of this repository - -`./config` contains Garden Linux specific build configuration for the kernel. - -`./fixes-debian` contains patches for the debian build if needed. -We apply all patches from debian by default. -In some cases, we need to make changes to those to get a working build. - -`./upstream-patches` contains kernel patches that are not included in debian's kernel, but are part of the Garden Linux kernel. - -`./prepare_source` contains a shell script that merges debian's kernel build repository with the upstream kernel sources. - -`./update-kernel.py` contains a script which helps keeping up with patch releases of the LTS kernel version. - -`.github/workflows/pr-if-new-kernel.yml` contains the workflow to create new PRs based on `./update-kernel.py` if new patch versions of the LTS kernel are available. - -`.github/workflows/build.yml` contains the workflow to build and release the kernel binaries. - -## Backports - -| branch | description | -| ------------- | -------------- | -| `main` | latest lts kernel we maintain (6.18) | -| `maint-6.12` | maintenance of source code for kernel 6.12 | -| `maint-6.6` | maintenance of source code for kernel 6.6 | -| `rel-1877` | backport for 1877, merge code from `maint-6.12` | -| `rel-1592` | backport for 1592, merge code from `maint-6.6` | - - -The main branch of this repository always contains the latest kernel available in Garden Linux, and in the nightly builds. -Typically, this will be the most recent long term support (LTS) line from kernel.org, but from time to time it might also be a 'stable' kernel that will become the next LTS. - -We maintain also older supported kernel versions, if they are required by supported Garden Linux versions. - -Any kernel version that we need to maintain other than the latest LTS in main, are maintained in `maint-` branches (e.g. `maint-6.6`). -Backport releases need to branch off from the respective `maint-` branch and include the corresponding `.container` file for target backport. - -Branches containing the `.container` file must be named according to the `rel-MAJOR` naming scheme (e.g. `rel-1443`). - -## How to do a backport from maint-X.Y branch - -``` -git checkout rel-MAJOR -git merge --squash origin/maint-x.y -# resolve merge conflicts -git commit -git push -# Pipeline builds new rel-MAJOR version -``` - -> [!Tip] -> You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) - -> [!Note] -> We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) - -## Automated kernel patch level upgrades - -A scheduled workflow scans a list of configured branches [see](https://github.com/gardenlinux/package-linux/blob/main/.github/workflows/pr-if-new-kernel.yml#L12), and bumps the patch level of the version defined in the prepare_source file. -The automation creates a PR if a new patch level is available. - -> [!Important] -> Note that build failures in this PR will not be visible in the way you are used to it. -> This is due to limitations on GitHub. -> Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. -> [See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). - -> [!Note] -> This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool diff --git a/README.md b/README.md new file mode 120000 index 0000000..d1d2016 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +docs/how-to/README.md \ No newline at end of file diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..e629ec0 --- /dev/null +++ b/docs/reference/README.md @@ -0,0 +1,88 @@ +--- +title: "Garden Linux Kernel Builds" +description: "How to build a Garden Linux Kernel" +migration_status: "adapt" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/reference/README.md +github_target_path: docs/reference/kernel-builds.md +--- + +# Kernel builds for Garden Linux + +This repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. +The build is based on [the debian kernel build](https://salsa.debian.org/kernel-team/linux). + +Garden Linux includes the latest LTS version of the kernel. + +## Components of this repository + +`./config` contains Garden Linux specific build configuration for the kernel. + +`./fixes-debian` contains patches for the debian build if needed. +We apply all patches from debian by default. +In some cases, we need to make changes to those to get a working build. + +`./upstream-patches` contains kernel patches that are not included in debian's kernel, but are part of the Garden Linux kernel. + +`./prepare_source` contains a shell script that merges debian's kernel build repository with the upstream kernel sources. + +`./update-kernel.py` contains a script which helps keeping up with patch releases of the LTS kernel version. + +`.github/workflows/pr-if-new-kernel.yml` contains the workflow to create new PRs based on `./update-kernel.py` if new patch versions of the LTS kernel are available. + +`.github/workflows/build.yml` contains the workflow to build and release the kernel binaries. + +## Backports + +| branch | description | +| ------------ | ----------------------------------------------- | +| `main` | latest lts kernel we maintain (6.18) | +| `maint-6.12` | maintenance of source code for kernel 6.12 | +| `maint-6.6` | maintenance of source code for kernel 6.6 | +| `rel-1877` | backport for 1877, merge code from `maint-6.12` | +| `rel-1592` | backport for 1592, merge code from `maint-6.6` | + +The main branch of this repository always contains the latest kernel available in Garden Linux, and in the nightly builds. +Typically, this will be the most recent long term support (LTS) line from kernel.org, but from time to time it might also be a 'stable' kernel that will become the next LTS. + +We maintain also older supported kernel versions, if they are required by supported Garden Linux versions. + +Any kernel version that we need to maintain other than the latest LTS in main, are maintained in `maint-` branches (e.g. `maint-6.6`). +Backport releases need to branch off from the respective `maint-` branch and include the corresponding `.container` file for target backport. + +Branches containing the `.container` file must be named according to the `rel-MAJOR` naming scheme (e.g. `rel-1443`). + +## How to do a backport from maint-X.Y branch + +``` +git checkout rel-MAJOR +git merge --squash origin/maint-x.y +# resolve merge conflicts +git commit +git push +# Pipeline builds new rel-MAJOR version +``` + +> [!Tip] +> You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) + +> [!Note] +> We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) + +## Automated kernel patch level upgrades + +A scheduled workflow scans a list of configured branches [see](https://github.com/gardenlinux/package-linux/blob/main/.github/workflows/pr-if-new-kernel.yml#L12), and bumps the patch level of the version defined in the prepare_source file. +The automation creates a PR if a new patch level is available. + +> [!Important] +> Note that build failures in this PR will not be visible in the way you are used to it. +> This is due to limitations on GitHub. +> Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. +> [See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). + +> [!Note] +> This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool From 74d19b624e155d242461ce825af944062e69a1d3 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 23 Apr 2026 08:25:13 +0200 Subject: [PATCH 2/4] docs: move explanation from gardenlinux repo and restructure Signed-off-by: Eike Waldt On-behalf-of: SAP --- README.md | 2 +- docs/explanation/kernel.md | 70 ++++++++++++++++ .../README.md => how-to/kernel-builds.md} | 81 +++++++++++++------ docs/reference/kernel-flavors.md | 41 ++++++++++ 4 files changed, 170 insertions(+), 24 deletions(-) create mode 100644 docs/explanation/kernel.md rename docs/{reference/README.md => how-to/kernel-builds.md} (59%) create mode 100644 docs/reference/kernel-flavors.md diff --git a/README.md b/README.md index d1d2016..ae68a5d 120000 --- a/README.md +++ b/README.md @@ -1 +1 @@ -docs/how-to/README.md \ No newline at end of file +docs/how-to/kernel-builds.md \ No newline at end of file diff --git a/docs/explanation/kernel.md b/docs/explanation/kernel.md new file mode 100644 index 0000000..5f4e81d --- /dev/null +++ b/docs/explanation/kernel.md @@ -0,0 +1,70 @@ +--- +title: "Garden Linux Kernel" +description: Why we build the kernel the way we build it +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" +migration_source: "00_introduction/kernel.md" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmang0ld, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/explanation/kernel.md +github_target_path: docs/explanation/kernel.md +--- + +# Kernel Philosophy + +Garden Linux aims towards a complete open, reproducible and easy-to-understand solution. That also includes all activities around the Kernel. +[Kernel.org](https://kernel.org) is the source of the official Linux kernels and therefore all kernels in Garden Linux are mainly based on this. Not to forget our Debian roots: we integrate with the build environment [Debian kernels](https://wiki.debian.org/Kernel) to support the Debian featureset to be compatible. Garden Linux tries to keep the amount of patches in the kernel diverging from Debian and kernel.org low, so everybody can easily support the Garden Linux kernel and no deep knowledge of Garden Linux internals is needed. + +## Kernel Versioning Strategy + +In contrast to Debian, Garden Linux integrates always with the latest Long Term Support kernel (LTS) and maintains this kernel at least for one overlapping period till the next kernel will be available. You can find the release categories and the time schedule for LTS releases also on [kernel.org](https://www.kernel.org/category/releases.html). +Garden Linux aims to integrate the latest long term release. + +### Why does Garden Linux not integrate the mainline stable? + +Mainline stable introduces features to the new Linux kernel, which happens every ~2 months. Some of those features affect the way e.g. container or network environment interact with the kernel and need some time to be adopted in surrounding tooling. Also some other feature introduce bugs, recognized after release and need to be reverted or other changes. In short: to avoid this we wait until a kernel version becomes a longterm stable and try to integrate always the latest long term stable and the one before to have a decent deprecation phase. +**Garden Linux takes advantage of these patches.** + +### A new long term kernel is released, when will it be integrated? + +We are probably on it, but feel free to open a Github issue. + +## Relationship to Debian + +Garden Linux 💚 Debian. + +Debian is free and open source software. There are good [reasons](https://www.debian.org/intro/why_debian) +to use Debian. In the following we explain our reasons in the kernel context. + +First, Debian provides an enterprise grade server operating system, +while protecting the claim to stay 100% free and open source. +Debian is rigorous when it comes to non-free software licenses, +also when it comes to the Linux Kernel. A prominent example of +what this means, is the extraction of non-free firmware from +the Linux Kernel. + +Debian scans licenses and patches out everything +that violates the claim to stay 100% free. Since Garden Linux shares this +approach, we benefit from Debian patches. + +Additionally, Debian provides a good kernel configuration, +which is used by Garden Linux as a base for configuration. +We extend this kernel configuration to our specific requirements during the +kernel integration process. + +Furthermore, Debian kernel [patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) are applied in most cases. + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics + + diff --git a/docs/reference/README.md b/docs/how-to/kernel-builds.md similarity index 59% rename from docs/reference/README.md rename to docs/how-to/kernel-builds.md index e629ec0..7344471 100644 --- a/docs/reference/README.md +++ b/docs/how-to/kernel-builds.md @@ -1,24 +1,28 @@ --- -title: "Garden Linux Kernel Builds" +title: "Kernel Builds" description: "How to build a Garden Linux Kernel" -migration_status: "adapt" +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" migration_approved: false github_org: gardenlinux github_repo: package-linux -github_source_path: docs/reference/README.md -github_target_path: docs/reference/kernel-builds.md +github_source_path: docs/how-to/kernel-builds.md +github_target_path: docs/how-to/kernel-builds.md --- -# Kernel builds for Garden Linux +# Kernel Builds -This repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. +The [package-linux](https://github.com/gardenlinux/package-linux) repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. The build is based on [the debian kernel build](https://salsa.debian.org/kernel-team/linux). Garden Linux includes the latest LTS version of the kernel. -## Components of this repository +## Components `./config` contains Garden Linux specific build configuration for the kernel. @@ -36,7 +40,7 @@ In some cases, we need to make changes to those to get a working build. `.github/workflows/build.yml` contains the workflow to build and release the kernel binaries. -## Backports +## Branch Structure | branch | description | | ------------ | ----------------------------------------------- | @@ -56,33 +60,64 @@ Backport releases need to branch off from the respective `maint-` b Branches containing the `.container` file must be named according to the `rel-MAJOR` naming scheme (e.g. `rel-1443`). -## How to do a backport from maint-X.Y branch +## How to Create Kernel Backports from `maint-X.Y` branch -``` +1. Checkout the appropriate release branch: + +```bash git checkout rel-MAJOR +``` + +2. Merge changes from the maintenance branch (replace x.y with the appropriate version): + +```bash git merge --squash origin/maint-x.y # resolve merge conflicts +``` + +3. Commit the changes: + +```bash git commit -git push -# Pipeline builds new rel-MAJOR version ``` -> [!Tip] -> You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) +4. Push the changes: -> [!Note] -> We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) +```bash +git push origin rel-MAJOR +``` + +5. The Github Workflow will now build the new rel-MAJOR version. + +:::tip +You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) +::: + +:::info +We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) +::: ## Automated kernel patch level upgrades A scheduled workflow scans a list of configured branches [see](https://github.com/gardenlinux/package-linux/blob/main/.github/workflows/pr-if-new-kernel.yml#L12), and bumps the patch level of the version defined in the prepare_source file. The automation creates a PR if a new patch level is available. -> [!Important] -> Note that build failures in this PR will not be visible in the way you are used to it. -> This is due to limitations on GitHub. -> Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. -> [See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). +:::warning +Note that build failures in this PR will not be visible in the way you are used to it. +This is due to limitations on GitHub. +Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. +[See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). +::: + +:::info +This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool +::: + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics -> [!Note] -> This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool + diff --git a/docs/reference/kernel-flavors.md b/docs/reference/kernel-flavors.md new file mode 100644 index 0000000..2eddeb4 --- /dev/null +++ b/docs/reference/kernel-flavors.md @@ -0,0 +1,41 @@ +--- +title: "Kernel Flavors" +description: Available kernel variants for different architectures and use cases +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/reference/kernel-flavors.md +github_target_path: docs/reference/kernel-flavors.md +--- + +# Kernel Flavors + +Garden Linux provides multiple kernel variants optimized for different architectures and deployment scenarios. + +## Available Flavors + +| Flavour | Architecture | Description | +| ----------- | ------------ | -------------------------------------------------------------- | +| amd64 | x86_64 | 64-bit PCs; includes Intel SGX, TDX, Mellanox SmartNIC support | +| cloud-amd64 | x86_64 | Cloud VMs (AWS, Azure, GCP) - stripped-down with cloud drivers | +| arm64 | aarch64 | 64-bit ARMv8 machines | +| cloud-arm64 | aarch64 | Cloud VMs (AWS, Azure, GCP) - stripped-down with cloud drivers | + +Cloud flavors disable graphics, USB, wireless, Bluetooth, and audio drivers +and enable Hyper-V, virtio, Xen, ENA (AWS), GVE (GCE), and MANA (Azure). + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics + + From 2aa385ce3b3c8c3f797af8541932eee561923e3b Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 29 Apr 2026 10:22:40 +0200 Subject: [PATCH 3/4] docs: change explanation title Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/explanation/kernel.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/kernel.md b/docs/explanation/kernel.md index 5f4e81d..bb41b3e 100644 --- a/docs/explanation/kernel.md +++ b/docs/explanation/kernel.md @@ -1,6 +1,6 @@ --- -title: "Garden Linux Kernel" -description: Why we build the kernel the way we build it +title: "Kernel" +description: Why we build the Garden Linux Kernel the way we build it related_topics: - /explanation/kernel.md - /how-to/kernel-builds.md From 9570d0f81eae4e1e500dd3f36ea845a2dce14357 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 30 Apr 2026 10:11:13 +0200 Subject: [PATCH 4/4] docs: change order Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/explanation/kernel.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/explanation/kernel.md b/docs/explanation/kernel.md index bb41b3e..df69f11 100644 --- a/docs/explanation/kernel.md +++ b/docs/explanation/kernel.md @@ -1,6 +1,7 @@ --- title: "Kernel" description: Why we build the Garden Linux Kernel the way we build it +order: 119 related_topics: - /explanation/kernel.md - /how-to/kernel-builds.md