feat(8-git-uformat-patch): init

8-git-uformat-patch/README.md

@@ -0,0 +1,55 @@
+# Managing patches for package sources with Git
+
+You're working on a package release for a software distribution, but you must
+apply some patches to the distribution package sources for the packaging to
+succeed.
+
+You have checked out two repositories:
+
+* a repository containing the source code of software you're packaging,
+* a repository containing the distribution package sources (package spec,
+  etc.), referencing the software source code
+
+You start patching files inside the build directory of the package.
+
+Once the patch works, you commit it to the software sources.
+
+Then use `git-uformat-patch` to generate patch files of the commits you've
+made to the software sources and store them in the distribution package's
+sources.
+
+Clean the build directory and rerun the build after applying the patches through
+the patch files you've just created. Rebasing, etc. works through the same
+mechanism.
+
+The patches are a shadow of the source code commits.
+
+This way, you can 
+
+* manage patches atomically through Git,
+* and prepare patches for upstream merge requests to the sources early, while
+  maintaining focus on packaging
+
+Whether learning along the way and looking for tutoring by the software author,
+or quickly making patches redundant through approved merge requests, atomicity
+in patch management through Git allows to give concise historic context.
+
+If you're packaging version 6 of some software, you would create patch files for
+all commits between now and the release tag in the software sources of the
+version you are packaging:
+
+```
+/source-repo $> sh git-uformat-patch.sh -o /distro-repo HEAD...v6
+```
+
+```
+/distro-repo $> patch -i ./*.patch
+```
+
+But you can also create patch files for only the top 3 commits:
+
+```
+/source-repo $> GITLOGOPTS='-3' sh git-uformat-patch.sh -o /distro-repo HEAD...v6
+```
+
+Run `sh git-uformat-patch.sh -h`, for more information.