README: document different behaviour of submodule vs. clone

[pve-kernel.git] / README

diff --git a/README b/README
index 8e2cadeb31a6dfb74c630ff829adcf0368d21762..6495a33b3524602b5dd0772f2762a9bad36eebb9 100644 (file)
--- a/README
+++ b/README
@@ -15,8 +15,6 @@ Additional/Updated Modules:
 
 - include latest e1000e driver from intel/sourceforge
 
-- include latest ixgbe driver from intel/sourceforge
-
 - include latest igb driver from intel/sourceforge
 
 - include native OpenZFS filesystem kernel modules for Linux
@@ -26,6 +24,32 @@ Additional/Updated Modules:
   For licensing questions, see: http://open-zfs.org/wiki/Talk:FAQ
 
 
+SUBMODULE
+=========
+
+We track the current upstream repository as submodule. Besides obvious
+advantages over tracking binary tar archives this also has some implications.
+
+For building the submodule directory gets copied into build/ and a few patches
+get applied with the `patch` tool. From a git point-of-view, the copied
+directory remains clean even with extra patches applied since it does not
+contain a .git directory, but a reference to the (still pristine) submodule:
+
+$ cat build/ubuntu-bionic/.git
+
+If you mistakenly cloned the upstream repo as "normal" clone (not via the
+submodule mechanics) this means that you have a real .git directory with its
+independent objects and tracking info when copying for building, thus git
+operates on the copied directory - and "sees" that it was dirtied by `patch`,
+and thus the kernel buildsystem sees this too and will add a '+' to the version
+as a result. This changes the output directories for modules and other build
+artefacts and let's then the build fail on packaging.
+
+So always ensure that you really checked it out as submodule, not as full
+"normal" clone. You can also explicitly set the LOCALVERSION variable to
+undefined with: `export LOCALVERSION= but that should only be done for test
+builds.
+
 RELATED PACKAGES:
 =================
 
@@ -55,6 +79,21 @@ git clone git://git.proxmox.com/git/pve-firmware.git
 NOTES:
 ======
 
+ABI versions, package versions and package name:
+------------------------------------------------
+
+We follow debian's versioning w.r.t ABI changes:
+
+https://kernel-team.pages.debian.net/kernel-handbook/ch-versions.html
+https://wiki.debian.org/DebianKernelABIChanges
+
+The debian/rules file has a target comparing the build kernel's ABI against the
+version stored in the repository and indicates when an ABI bump is necessary.
+An ABI bump within one upstream version consists of incrementing the KREL
+variable in the Makefile, rebuilding the packages and running 'make abiupdate'
+(the 'abiupdate' target in 'Makefile' contains the steps for consistently
+updating the repository).
+
 Watchdog blacklist
 ------------------
 
@@ -69,7 +108,7 @@ Additional information
 We use the default configuration provided by Ubuntu, and apply
 the following modifications:
 
-see debian/rules (PVE_CONFIG_OPTS)
+NOTE: For the exact and current list see debian/rules (PVE_CONFIG_OPTS)
 
 - enable INTEL_MEI_WDT=m (to allow disabling via patch)
 
@@ -95,20 +134,13 @@ see debian/rules (PVE_CONFIG_OPTS)
         CONFIG_BLK_DEV_NBD=m
         CONFIG_BLK_DEV_RBD=m
 
-- set LOOP_MIN_COUNT to 8 (debian defaults)
-        CONFIG_BLK_DEV_LOOP_MIN_COUNT=8
-
-- disable module signatures (CONFIG_MODULE_SIG)
-
-- enable IBM JFS file system
+- enable IBM JFS file system as module
 
-  This is disabled in RHEL kernel for no real reason, so we enable
-  it as requested by users (bug #64)
+  enable it as requested by users (bug #64)
 
-- enable apple HFS and HFSPLUS
+- enable apple HFS and HFSPLUS as module
 
-  This is disabled in RHEL kernel for no real reason, so we enable
-  it as requested by users
+  enable it as requested by users
 
 - enable CONFIG_BCACHE=m (requested by user)