doc: improve subtree check instructions

mfaulk · Nov 9, 2020 · c0c05eb · c0c05eb
1 parent 9069364
commit c0c05eb
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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)