Update docs to reflect multiple patches

Author: spoorcc

dfetch/commands/diff.py

@@ -1,9 +1,9 @@
 """*Dfetch* can create a patch file with your local changes to the external project.
 
 If you've found any issues with the remote project, you can fix them within the context of your project.
-To help the upstream project, you can generate a patch file
-that can be applied by the upstream maintainer. The patch will be generated using the version control system
-of your main project that contains the manifest.
+To help the upstream project, you can generate a patch file that can be applied by the upstream maintainer.
+The patch will be generated using the version control system
+of your main project (also referred to as superproject) that contains the manifest.
 
 To generate a patch, *Dfetch* requires two revisions to identify the changes. You can
 provide these through the ``--revs`` argument.
@@ -64,7 +64,10 @@
 
 Updating the patch
 ======================
-If you have further changes to a project with a patch, you can update the patch by first reversing the patch, using
+If you have further changes to a project with a patch, you can create an additional patch if the changes are
+unrelated, or you can update the patch as described below.
+
+First step is to reverse the original patch, using
 ``apply`` and with the ``--directory`` argument as shown above. To reverse the patch you also require the ``-R``.
 This will return the project to the state before the patch was applied. You can then stage the project and re-apply
 the patch to the project to have an editable patch.

dfetch/manifest/project.py

@@ -223,9 +223,9 @@
 
 Patch
 #####
-*DFetch* promotes upstreaming changes, but also allows local changes. These changes can be managed with a local patch
-file. *DFetch* will apply the patch file every time a new upstream version is fetched. The patch file can be specified
-with the ``patch:`` attribute.
+*DFetch* promotes upstreaming changes, but also allows local changes. These changes can be managed with local patch
+files. *DFetch* will apply the patch files in order every time a new upstream version is fetched. The patch file can
+be specified with the ``patch:`` attribute. This can be a single patch file or multiple.
 
 .. code-block:: yaml
 

dfetch/project/metadata.py

@@ -127,7 +127,7 @@ def hash(self) -> str:
 
     @property
     def patch(self) -> list[str]:
-        """The applied patch as stored in the metadata."""
+        """The list of applied patches as stored in the metadata."""
         return self._patch
 
     @property

doc/manifest.rst

@@ -92,7 +92,7 @@ Below an overview of all possible fields on the manifest. The bold items are man
                   type: string
                 patch:
                   type: string
-                  description: Patch to apply after fetching see :ref:`Patch`.
+                  description: One or more patches to apply after fetching, see :ref:`Patch`.
                 vcs:
                   type: string
                   description: Version control system used by the project. See :ref:`VCS type` for details.

doc/static/uml/update.puml

@@ -45,8 +45,10 @@ partition "Perform Update" {
     :Fetch target:
     revision/tag/branch;
 
-    if (Patch given?) then (yes)
-        :Apply patch;
+    if (Patches given?) then (yes)
+        while (More patches?) is (yes)
+            :Apply next patch;
+        endwhile (no)
     endif
 }
 

doc/vendoring.rst

@@ -254,7 +254,8 @@ They *mitigate* vendoring risks; they do not eliminate them.
     **Rationale** The vendored dependency may diverge, keeping it the same as upstream makes it easy to keep following
     upstream updates. Also by upstreaming any changes, more people outside the project can profit from any fixes.
 
-    *Dfetch* addresses this by providing a ``dfetch diff`` (:ref:`Diff`) command and a ``patch`` :ref:`Patch` attribute in the manifest.
+    *Dfetch* addresses this by providing a ``dfetch diff`` (:ref:`Diff`) command and a ``patch`` (:ref:`Patch`) attribute in the manifest.
+    This attribute can point to one or more patches that should be applied to the vendored dependency.
     Next to this there is a CI system to detect local changes using :ref:`Check`.
 
 .. admonition :: Continuous Automation and Security Scanning