From fad7a5050da12748d783a828690146b9f60420b1 Mon Sep 17 00:00:00 2001 From: Jens Reidel Date: Tue, 4 Nov 2025 00:22:39 +0100 Subject: [PATCH] docs: Add kernel version packaging recommendations Signed-off-by: Jens Reidel Part-of: --- docs/index.md | 1 + docs/kernel-versions.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 docs/kernel-versions.md diff --git a/docs/index.md b/docs/index.md index f434e0642..e582d1448 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,5 +15,6 @@ in pmaports and the processes around device categorization. approval-rules device-categorization + kernel-versions ``` diff --git a/docs/kernel-versions.md b/docs/kernel-versions.md new file mode 100644 index 000000000..b1cffed80 --- /dev/null +++ b/docs/kernel-versions.md @@ -0,0 +1,31 @@ +# Kernel Versions + +Generally speaking, maintainers have the freedom to package any kernel version +they desire for their devices. However, the choice affects the categories that +the device may be eligible for and we strongly recommend following some +additional guidelines for which kernel version to package for a device. + +## Categorization + +Devices with a close-to-mainline kernel usually reside in `testing` and can be +moved to `community` or `main` later if they meet the necessary +[requirements](./device-categorization.md). Devices using a downstream (i.e. +vendor-provided) kernel are packaged in the `downstream` or `archived` +categories. + +## What To Package + +We strongly advise **against** using any +[linux-next](https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git) +version as the kernel packaged for devices. linux-next is used for integration +testing and as a base for patch submission, but is by no means stable and +therefore we discourage packaging it. One exception to this is the +`device-postmarketos-trailblazer` device package - it is intended to be a +bleeding edge target reflecting the very latest state of upstream. + +Further, we do not recommend packaging the first release candidate (-rc1) +tagged after the merge window is closed. The first release candidate introduces +a lot of new changes, after which only fixes are admitted into the kernel tree. +Therefore, subsequent release candidates tend to be more stable than the first. +We recommend waiting until at least -rc2 before packaging a new major kernel +release.