From: Álvaro Fernández Rojas <noltari@gmail.com>
Date: Wed, 11 Jun 2025 06:15:35 +0000 (+0200)
Subject: generic: improve patches documentation
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F19092%2Fhead;p=thirdparty%2Fopenwrt.git

generic: improve patches documentation

It's time to give the patches documentation some love by:
- Using Markdown.
- Differentiating between generic and specific target patches.
- Adding deeper explanation about patch numbering.

Link: https://github.com/openwrt/openwrt/pull/19092
Signed-off-by: Álvaro Fernández Rojas <noltari@gmail.com>
---

diff --git a/target/linux/generic/PATCHES b/target/linux/generic/PATCHES
deleted file mode 100644
index 86ced468048..00000000000
--- a/target/linux/generic/PATCHES
+++ /dev/null
@@ -1,20 +0,0 @@
-The patches-* subdirectories contain the kernel patches applied for every
-OpenWrt target. All patches should be named 'NNN-lowercase_shortname.patch'
-and sorted into the following categories:
-
-0xx - upstream backports
-1xx - code awaiting upstream merge
-2xx - kernel build / config / header patches
-3xx - architecture specific patches
-4xx - mtd related patches (subsystem and drivers)
-5xx - filesystem related patches
-6xx - generic network patches
-7xx - network / phy driver patches
-8xx - other drivers
-9xx - uncategorized other patches
-
-ALL patches must be in a way that they are potentially upstreamable, meaning:
-
-- they must contain a proper subject
-- they must contain a proper commit message explaining what they change
-- they must contain a valid Signed-off-by line
diff --git a/target/linux/generic/PATCHES.md b/target/linux/generic/PATCHES.md
new file mode 100644
index 00000000000..0462a59f922
--- /dev/null
+++ b/target/linux/generic/PATCHES.md
@@ -0,0 +1,84 @@
+# OpenWrt kernel patches
+
+All patches must be in a way that they are potentially upstreamable, meaning:
+
+* They must contain a proper subject.
+* They must contain a proper commit message explaining what they change and why.
+* They must contain a valid Signed-off-by line.
+
+The build system applies the patches in the following order:
+
+1. target/linux/generic/backport-*/
+2. target/linux/generic/pending-*/
+3. target/linux/generic/hack-*/
+4. target/linux/`<target name>`/patches-*/
+
+## OpenWrt generic
+
+The generic target patches are applied to every OpenWrt target before any of the specific target patches are applied.
+
+### backport
+
+The `backport-*` subdirectories contain the kernel patches backported from newer kernels.
+
+In order to save naming space for newer patches to come, when adding a new subset of patches which are related between them the following naming convention shall be used: `NNN-SS-vX.Y-lowercase_shortname.patch`.
+For single patches, the following naming convention shall be used instead: `NNN-vX.Y-lowercase_shortname.patch`.
+
+| Item  | Description              |
+| ----- |:------------------------:|
+| NNN   | Main patch number.       |
+| SS    | Subset patch number.     |
+| vX.Y  | Upstream kernel version. |
+
+### hack
+
+The `hack-*` subdirectories contain the downstream kernel patches that are less likely to be accepted upstream but are still needed in OpenWrt.
+Some of these patches are potentially upstreamable if properly reworked and others aren't simply worth the effort.
+
+All patches should be named `NNN-lowercase_shortname.patch`.
+
+### pending
+
+The `pending-*` subdirectories contain the kernel patches awaiting upstream merge.
+
+All patches should be named `NNN-lowercase_shortname.patch`.
+
+### Patch number guidelines
+
+The following patch numbering guidelines shall be followed:
+
+| NNN  | Description                     |
+| ---- |:-------------------------------:|
+| 0xx  | -                               |
+| 1xx  | -                               |
+| 2xx  | Kernel build / config / header  |
+| 3xx  | Architecture specific           |
+| 4xx  | MTD                             |
+| 5xx  | Filesystem                      |
+| 6xx  | Generic network                 |
+| 7xx  | Network / PHY                   |
+| 8xx  | Other drivers                   |
+| 9xx  | Uncategorized                   |
+
+## OpenWrt targets
+
+The `patches-*` subdirectories contain the kernel patches applied for every OpenWrt target.
+
+All patches should be named `NNN-lowercase_shortname.patch`.
+
+### Patch number guidelines
+
+The following patch numbering guidelines shall be followed:
+
+| NNN  | Description                     |
+| ---- |:-------------------------------:|
+| 0xx  | Upstream backports              |
+| 1xx  | Awaiting upstream merge         |
+| 2xx  | Kernel build / config / header  |
+| 3xx  | Architecture specific           |
+| 4xx  | MTD                             |
+| 5xx  | Filesystem                      |
+| 6xx  | Generic network                 |
+| 7xx  | Network / PHY                   |
+| 8xx  | Other drivers                   |
+| 9xx  | Uncategorized                   |