[yocto] IMPORTANT: do_patch() fuzz warnings and how to deal with them

[Alexander Kanavin]

*Executive summary*

do_patch() will shortly start issuing warnings when recipe patches are 
applied with some of the patch context ignored. This email explains why 
this is necessary, and how the warnings can be eliminated.

*What is patch fuzz?*

Patch fuzz is a situation when the patch tool ignores some of the 
context lines in order to apply the patch. Consider this example:

Patch to be applied:

========
context line 1
context line 2
context line 3
+newly added line
context line 4
context line 5
context line 6
========

Original source code:

========
different context line 1
different context line 2
context line 3
context line 4
different context line 5
different context line 6
========

Outcome:

========
different context line 1
different context line 2
context line 3
newly added line
context line 4
different context line 5
different context line 6
========

Chances are, the newly added line was actually added in a completely 
wrong location, or it was already in the original source, and was added 
for the second time. This is especially possible, if the context line 3 
and 4 are blank or have only generic things in them like #endif or }. 
Even worse, there is currently no warning when this happens, and 
depending on the patched code, it can (and does) still compile without 
errors.

*What is changing*

When patch fuzz is detected, there will be a warning printed, similar to 
this:

     WARNING: vulkan-1.0.61.1-r0 do_patch:
     Some of the context lines in patches were ignored. This can lead to 
incorrectly applied patches.
     The context lines in the patches can be updated with devtool:

         devtool modify <recipe>
         devtool finish --force-patch-refresh <recipe> <layer_path>

     Then the updated patches and the source tree (in devtool's workspace)
     should be reviewed to make sure the patches apply in the correct place
     and don't introduce duplicate lines (which can, and does happen
     when some of the context is ignored).
     Details:
     Applying patch demos-Don-t-build-tri-or-cube.patch
     patching file demos/CMakeLists.txt
     Hunk #1 succeeded at 63 (offset 2 lines).
     Hunk #2 succeeded at 76 with fuzz 1 (offset 2 lines).

*How to elimimate the warnings?*

Use devtool command as explained by the warning. First, unpack the 
source into devtool workspace:

	devtool modify <recipe>

This will apply all the patches, and create new commits out of them in 
the workspace - with the patch context updated.

Then, replace the patches in the recipe layer:

         devtool finish --force-patch-refresh <recipe> <layer_path>

The patch updates need be reviewed (preferably, with a side-by-side diff 
tool) to ensure they are indeed doing the right thing:

1) they get applied in the correct location;
2) they do not introduce duplicate lines, or otherwise do things that 
are not anymore necessary.

To confirm these things, you can also review the patched source code in 
devtool's workspace, typically in <build_dir>/workspace/sources/<recipe>/

Once the review is done, you can create and publish a layer commit with 
the patch updates that modify the context. Devtool may also refresh 
other things in the patches, those can be discarded.


Alex