[pve-devel] [PATCH] README: document different behaviour of submodule vs. clone

[Thomas Lamprecht]

Signed-off-by: Thomas Lamprecht <t.lamprecht at proxmox.com>
---
 README | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README b/README
index db997a7..f904269 100644
--- a/README
+++ b/README
@@ -24,6 +24,35 @@ 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. Normally one would think that this makes the
+directory dirty, from a git POV, but the .git in this build copy is not a "real"
+git directory but merely points to the submodule definition in the pve-kernel
+repository, e.g. in the current Bionic case:
+pve-kernel/.git/modules/submodules/ubuntu-bionic
+which in turn points to the real submodule at:
+pve-kernel/submodules/ubuntu-bionic
+
+so any git operation in the temporal build directory gets "routed" to it's real
+backing submodule directory - where the source state is still clean.
+
+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 it's
+independent objects and tracking info when copying for building, thus git
+operates on the temporal 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, as example, modules 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.
+
 RELATED PACKAGES:
 =================
 
-- 
2.19.1