From c0c05ebb34f97af24471748eb38bd671b91a2c3e Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 12 Jun 2020 12:33:00 +0200
Subject: [PATCH] doc: improve subtree check instructions

---
 doc/developer-notes.md         | 33 +++++++++++++++++++++++++++++++++
 test/lint/README.md            |  6 ++++++
 test/lint/git-subtree-check.sh |  2 +-
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 8547e1136..c4f1892ad 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -314,6 +314,39 @@ Source code organization
 #endif // ZCASH_FOO_BAR_H
 ```
 
+Subtrees
+----------
+
+Several parts of the repository are subtrees of software maintained elsewhere.
+
+Some of these are maintained by active developers of Bitcoin Core, in which case changes should probably go
+directly upstream without being PRed directly against the project. They will be merged back in the next
+subtree merge.
+
+Others are external projects without a tight relationship with our project. Changes to these should also
+be sent upstream, but bugfixes may also be prudent to PR against Bitcoin Core so that they can be integrated
+quickly. Cosmetic changes should be purely taken upstream.
+
+There is a tool in `test/lint/git-subtree-check.sh` ([instructions](../test/lint#git-subtree-checksh)) to check a subtree directory for consistency with
+its upstream repository.
+
+Current subtrees include:
+
+- src/leveldb
+  - Upstream at https://github.com/google/leveldb ; Maintained by Google, but
+    open important PRs to Core to avoid delay.
+  - **Note**: Follow the instructions in [Upgrading LevelDB](#upgrading-leveldb) when
+    merging upstream changes to the LevelDB subtree.
+
+- src/secp256k1
+  - Upstream at https://github.com/bitcoin-core/secp256k1/ ; actively maintained by Core contributors.
+
+- src/crypto/ctaes
+  - Upstream at https://github.com/bitcoin-core/ctaes ; actively maintained by Core contributors.
+
+- src/univalue
+  - Upstream at https://github.com/bitcoin-core/univalue ; actively maintained by Core contributors, deviates from upstream https://github.com/jgarzik/univalue
+
 Scripted diffs
 --------------
 
diff --git a/test/lint/README.md b/test/lint/README.md
index d4215a52d..ad90147b4 100644
--- a/test/lint/README.md
+++ b/test/lint/README.md
@@ -16,6 +16,12 @@ maintained:
 * for `src/univalue`: https://github.com/bitcoin-core/univalue.git (branch master)
 * for `src/crypto/ctaes`: https://github.com/bitcoin-core/ctaes.git (branch master)
 
+To do so, add the upstream repository as remote:
+
+```
+git remote add --fetch secp256k1 https://github.com/bitcoin-core/secp256k1.git
+```
+
 Usage: `git-subtree-check.sh DIR (COMMIT)`
 
 `COMMIT` may be omitted, in which case `HEAD` is used.
diff --git a/test/lint/git-subtree-check.sh b/test/lint/git-subtree-check.sh
index 7b5707a17..1f847f489 100755
--- a/test/lint/git-subtree-check.sh
+++ b/test/lint/git-subtree-check.sh
@@ -81,7 +81,7 @@ fi
 
 # get the tree in the subtree commit referred to
 if [ "d$(git cat-file -t $rev 2>/dev/null)" != dcommit ]; then
-    echo "subtree commit $rev unavailable: cannot compare" >&2
+    echo "subtree commit $rev unavailable: cannot compare. Did you add and fetch the remote?" >&2
     exit
 fi
 tree_subtree=$(git show -s --format="%T" $rev)