From d4db7ccbde93381c9dca61900245fb4ef107ad20 Mon Sep 17 00:00:00 2001
From: Leonid Pliushch <leonid.pliushch@gmail.com>
Date: Sun, 26 Dec 2021 19:34:35 +0200
Subject: [PATCH] CONTRIBUTING.md: patch creation how-to

---
 CONTRIBUTING.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f4a1713f..98cd76c0a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -330,6 +330,54 @@ Use of forks is allowed only under a good reason.
 
 More about `build.sh` variables you can read on [developer's wiki](https://github.com/termux/termux-packages/wiki/Creating-new-package#table-of-available-package-control-fields).
 
+### Creating patch files
+
+Many packages will require changes that can't be done through configuring
+build system. In this cases you need to directly modify the source code
+and obtain files that describe your changes in machine readable format.
+
+We use patches made in [Unified Format](https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html)
+generated by either GNU `diff`, `git` or other compatible utility.
+
+See below on how to make a patch with GNU `diff`:
+
+1. Get source code, for example with this command:
+
+   ```
+   cd ./packages/your-package
+   (source build.sh 2>/dev/null; curl -LO "$TERMUX_PKG_SRCURL")
+   ```
+
+2. Extract tarball and make a copy of source code tree:
+
+   ```
+   tar xf package-1.0.tar.gz
+   cp -a package-1.0 package-1.0.mod
+   ```
+
+3. Change current directory to source code tree:
+
+   ```
+   cd package-1.0.mod
+   ```
+
+4. Make changes:
+
+   ```
+   vim sourcefile.c
+   ```
+
+5. Generate difference between original and modified sources:
+
+   ```
+   cd ..
+   diff -uNr package-1.0 package-1.0.mod > very-nice-improvement.patch
+   ```
+
+Patch file names should be self descriptive, so it will be easier for other
+people to understand what your patch does. Also it is preferred that every
+modification is stored in a separate patch file.
+
 ## Updating packages
 
 [![asciicast](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG.svg)](https://asciinema.org/a/gVwMqf1bGbqrXmuILvxozy3IG?autoplay=1&speed=2.0)
@@ -430,4 +478,3 @@ No LICENSE file was installed for ...
 
 This error happens when build system cannot find license file and it should be
 specified manually through `TERMUX_PKG_LICENSE_FILE`.
-