doc: dev manual: proof-read and update the "Patching Packages" section

Remind the reader to upstream their patches, mention the layer
mechanism for search order, fix the logical structure of the whole
chapter by removing the superfluous "Creating Patches for a Package"
header, mention why `--git` can break packages, and general
proof-reading and typo correction.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

1 files changed, 33 insertions, 19 deletions

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index d79ebdba7..3dcaeb3d3 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -494,7 +494,7 @@ At this stage things can fail:
 
 If the ``configure`` script is not cross compile aware, we are out of
 luck. We must patch the source archive in this case to make it work.
-Refer to section :ref:`configure_rebuild` on how to use
+Refer to the section :ref:`configure_rebuild` on how to use
 PTXdist’s features to simplify this task.
 If the package depends on external components, these components might
 be already part of PTXdist. In this case we just have to add this
@@ -1255,14 +1255,28 @@ There can be various reasons why a package must be patched:
 
 -  or anything else (this case is the most common one)
 
-PTXdist handles patching automatically. After extracting the archive,
-PTXdist checks for the existence of a patch directory with the same name
-as the package. If our package’s name is ``foo-1.1.0``, PTXdist searches
-for patches in:
+Ideally, those problems should be adressed in the original project,
+so any patches you add to your BSP or to PTXdist should also be submitted upstream.
+The upstream project can often provide better feedback, they can integrate your
+patch into a new release, and also maintain your changes as part of the project.
+This way we make sure that all advantages of the open source idea work for us;
+and your patch can be removed again later when a new release of the project is
+integrated into your BSP or into PTXdist.
 
-#. project (``./patches/foo-1.1.0``)
+PTXdist handles patching automatically.
+After extracting the archive of a package, PTXdist checks for the existence of
+a patch directory named like its `<PKG>` variable.
+Take an exemplary package `foo` with version `1.1.0`:
+The variable `FOO` will have the value ``foo-1.1.0``, so PTXdist will look for
+a patch directory named ``foo-1.1.0`` in the following locations:
 
-#. platform (``./configs/|ptxdistPlatformConfigDir|/patches/foo-1.1.0``)
+#. the current layer:
+
+   a. project (``./patches/foo-1.1.0``)
+   b. platform (``./configs/|ptxdistPlatformConfigDir|/patches/foo-1.1.0``)
+
+#. any :ref:`base layers <layers-in-ptxdist>`,
+   applying the same search order as above for each layer recursively
 
 #. ptxdist (``<ptxdist/installation/path>/patches/foo-1.1.0``)
 
@@ -1272,9 +1286,6 @@ PTXdist installation. This can be useful if a project sticks to a
 specific PTXdist revision but fixes from a more recent revision of
 PTXdist should be used.
 
-Creating Patches for a Package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 PTXdist uses the utilities *git*, *patch* or *quilt* to work with
 patches or patch series. We recommend *git*, as it can manage patch
 series in a very easy way.
@@ -1331,7 +1342,7 @@ Using Git
 """""""""
 
 Create the patch directory like above for *quilt*,
-but only add an empty series file
+but only add an empty series file:
 
 .. code-block:: text
 
@@ -1351,8 +1362,9 @@ and import the package source as the first commit.
 .. note:: Optionally, you can enable the setting *Developer Options →
   use git to apply patches* in `ptxdist setup` to get this behaviour
   as a default for every package.
-  However, note that this setting is still experimental and can lead to
-  failures for some packages.
+  However, note that this setting is meant for development only, and can lead
+  to failures – some packages try to determine if they are being compiled from
+  a Git source tree, and behave differently in that case.
 
 Then you can change into the package build directory
 (``platform-<name>/build-target/foo-1.1.0``),
@@ -1367,8 +1379,8 @@ The Git history should now look something like this:
     * 65a360c2bd60 strfry.c: frobnicate the excusator
     * fdc315f6844c (tag: foobar-1.1.0, tag: base) initial commit
 
-Finally, call ``git ptx-patches`` to regenerate the patch series in the
-``patches/foo-1.1.0`` folder.
+Finally, call ``git ptx-patches`` to transform those Git commits into the patch
+series in the ``patches/foo-1.1.0`` folder.
 This way they don't get lost when cleaning the package.
 
 .. note:: PTXdist will only create a Git repository for packages with
@@ -1379,7 +1391,7 @@ This way they don't get lost when cleaning the package.
 
 Both approaches (Git and quilt) are not suitable for modifying files
 that are autogenerated in autotools-based buildsystems.
-Refer to section :ref:`configure_rebuild` on how PTXdist can
+Refer to the section :ref:`configure_rebuild` on how PTXdist can
 handle this special task.
 
 Adding More Patches to a Package
@@ -1393,17 +1405,17 @@ installation directories, NEVER, NEVER, NEVER). Due to the search order
 in which PTXdist searches for patches for a specific package, we can
 copy the global patch series to our local project directory. Now we have
 the permissions to add more patches or modify the existing ones. Also
-*quilt* is our friend here to manage the patch series.
+*quilt* and *git* are our friends here to manage the patch series.
 
 If we think that our new patches are valuable also for others, or they
 fix an error, it could be a good idea to send these patches to PTXdist
-mainline.
+mainline, and to the upstream project too.
 
 
 .. _configure_rebuild:
 
 Modifying Autotoolized Packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Autotoolized packages are very picky when automatically generated files
 get patched. The patch order is very important in this case and
@@ -1631,6 +1643,8 @@ convenient way to crate simple templates. It is also possible to create
 more files. For examples, the builtin ``genimage`` template creates a extra
 config file for the new package.
 
+.. _layers-in-ptxdist:
+
 Layers in PTXdist
 -----------------