From 788f004bb1e598583531c9858d0ab49f26626322 Mon Sep 17 00:00:00 2001
From: Kai Krakow <kai@kaishome.de>
Date: Thu, 19 Dec 2024 23:37:36 +0100
Subject: [PATCH] xpadneo: Add documentation about testing pull requests

Forks used for pull requests should not have tags. This is a problem
for our installer. To properly work with forks, these should be added
as a git remote instead. To still get the benefits of isolated
directories, git worktrees can be used instead.

Place a hint in the installer if this problem may occur, and also add
some documentation on how to use these features of git.

Signed-off-by: Kai Krakow <kai@kaishome.de>
---
 docs/TESTING.md  | 35 +++++++++++++++++++++++++++++++++++
 lib/installer.sh |  3 +++
 2 files changed, 38 insertions(+)
 create mode 100644 docs/TESTING.md

diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 00000000..35795042
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,35 @@
+## Testing and Development
+
+### Working with Pull Requests
+
+If working with pull requests, do not clone a fork of the other repository.
+The installer needs the original version tags to properly work and to have
+correct version tags that have not been tampered with.
+
+It is always recommended to add additional remotes for the forks to your
+already existing local clone.
+
+To do this, follow these steps. This example uses kakra/xpadneo as a fork:
+```bash
+# checkout a clone from the original repository
+git clone https://github.com/atar-axis/xpadneo.git
+cd xpadneo
+
+# add the fork for the pull request as a clone
+git remote add kakra https://github.com/kakra/xpadneo.git
+git remote update
+
+# option 1: switch to another branch within this directory
+git switch -C local/branch/name kakra/remote/branch/name
+
+# option 2: setup a git workdir to use an isolated directory
+git worktree add ../xpadneo-kakra -B local/branch/name kakra/remote/branch/name
+
+# to update to the latest version of a pull request
+git remote update --prune
+
+# then reset your outdated copy of the branch
+git reset --merge kakra/remote/branch/name # tries keeping your local modifications
+git reset --hard kakra/remote/branch/name  # discards your local modifications
+```
+
diff --git a/lib/installer.sh b/lib/installer.sh
index 47100e24..7d7b2d4e 100644
--- a/lib/installer.sh
+++ b/lib/installer.sh
@@ -14,6 +14,9 @@ __version() {
 		echo >&2 "ERROR: sudo git config --global --add safe.directory \$PWD"
 		echo >&2 "ERROR: to trust this git checkout for the root user."
 		echo >&2 "ERROR: See https://github.com/atar-axis/xpadneo/issues/346"
+		echo >&2
+		echo >&2 "HINT: Do not clone forks directly, add them as remotes to your"
+		echo >&2 "HINT: original clone. See docs/TESTING.md"
 		exit 3
 	}
 }