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

[Thomas Lamprecht]

On 10/24/18 7:19 AM, Fabian Grünbichler wrote:
> 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?

LOCALVERSION can be unset to address this, removing .git in the build copy
solves it obviously too - as the kernel has no chance to track dirty status,
and it seems they don't traverse their kernel source root boundary to check
if a higher locate .git is dirty.

See:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/setlocalversion

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

s/pristine/original or unchanged?

> 
> $ 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?

Hmm, yeah, sounds OK

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

OK

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

copied sounds "better", IMO.

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

OK.

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

OK.

> 
>> +
>> +So always ensure that you really checked it out as submodule, not as full
>> +"normal" clone.
> 
> drop this to keep it a bit shorter?

Hmm, it's a short sentence and a TL;DR for what to ensure, I'd keep it

Much thanks for looking at this!

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