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

[Fabian Grünbichler]

LGTM in general, some phrasing inline. I assume you tested other ways to
prevent this issue while investigating? e.g., removing the .git entirely
after copying, or setting some kernel build flag?

On Tue, Oct 23, 2018 at 04:07:31PM +0200, Thomas Lamprecht wrote:
> 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

starting from Normally:

>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

> +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.

drop this?

> +
> +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

s/it's/its

> +independent objects and tracking info when copying for building, thus git
> +operates on the temporal directory - and "sees" that it was dirtied by `patch`,

s/temporal/temporary or s/temporal/copied ?

> +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

s/,as example, modules/modules and other build artefacts

> +let's then the build fail on packaging.

makes the build fail. ?

> +
> +So always ensure that you really checked it out as submodule, not as full
> +"normal" clone.

drop this to keep it a bit shorter?

> +
>  RELATED PACKAGES:
>  =================
>  
> -- 
> 2.19.1
>