[tor-commits] [tor/master] scripts/git: Improve branch list comments

[teor at torproject.org]

commit c80694deccb6f7d00cf97415a75f0c85fabd9131
Author: teor <teor at torproject.org>
Date:   Wed Jan 15 12:28:00 2020 +1000

    scripts/git: Improve branch list comments
    
    Hopefully, these explanations make it easier to get the next branch
    transition right.
    
    Part of 32772.
---
 scripts/git/git-merge-forward.sh | 15 ++++++++++-----
 scripts/git/git-pull-all.sh      |  3 +--
 scripts/git/git-push-all.sh      | 11 +++++++----
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/scripts/git/git-merge-forward.sh b/scripts/git/git-merge-forward.sh
index 8e61f6e64..bbc5047cb 100755
--- a/scripts/git/git-merge-forward.sh
+++ b/scripts/git/git-merge-forward.sh
@@ -87,8 +87,10 @@ TOR_WKT_NAME=${TOR_WKT_NAME:-"tor-wkt"}
 # New arrays need to be in the WORKTREE= array else they aren't considered.
 #
 # Only used in test branch mode
-# There is no previous branch to merge forward, so the second and fifth items
-# must be blank ("")
+# We create a test branch for the earliest maint branch.
+# But it's the earliest maint branch, so we don't merge forward into it.
+# Since we don't merge forward into it, the second and fifth items must be
+# blank ("").
 MAINT_035_TB=( "maint-0.3.5" "" "$GIT_PATH/$TOR_WKT_NAME/maint-0.3.5" \
     "_035" "")
 # Used in maint/release merge and test branch modes
@@ -172,8 +174,8 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
   # maint/release merge mode
   #
-  # List of all worktrees to work on. All defined above. Ordering is important.
-  # Always the maint-* branch BEFORE then the release-*.
+  # List of all worktrees to merge forward into. All defined above.
+  # Ordering is important. Always the maint-* branch BEFORE the release-*.
   WORKTREE=(
     # We don't merge forward into MAINT_035_TB[@], because it's the earliest
     # maint branch
@@ -193,7 +195,10 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
 else
 
-  # Test branch mode: merge to maint only
+  # Test branch mode: base test branches on maint branches only
+  #
+  # List of all worktrees to create test branches from. All defined above.
+  # Ordering is important. All maint-* branches, including the earliest one.
   WORKTREE=(
     # We want a test branch based on the earliest maint branch
     MAINT_035_TB[@]
diff --git a/scripts/git/git-pull-all.sh b/scripts/git/git-pull-all.sh
index 6e02093ad..c8d115da0 100755
--- a/scripts/git/git-pull-all.sh
+++ b/scripts/git/git-pull-all.sh
@@ -91,8 +91,7 @@ EOF
 # Git worktrees to manage #
 ###########################
 
-# List of all worktrees to work on. All defined above. Ordering is important.
-# Always the maint-* branch first then the release-*.
+# List of all worktrees to pull. All defined above. Ordering is not important.
 WORKTREE=(
   MAINT_035[@]
   RELEASE_035[@]
diff --git a/scripts/git/git-push-all.sh b/scripts/git/git-push-all.sh
index 466b843f3..0abddc802 100755
--- a/scripts/git/git-push-all.sh
+++ b/scripts/git/git-push-all.sh
@@ -97,9 +97,10 @@ PUSH_SAME=${TOR_PUSH_SAME:-0}
 # Argument processing #
 #######################
 
-# Controlled by the -t <test-branch-prefix> option. The test branch base
-# name option makes git-merge-forward.sh create new test branches:
-# <tbbn>_035, <tbbn>_040, ... , <tbbn>_master, and merge forward.
+# Controlled by the -t <test-branch-prefix> option. The test branch prefix
+# option makes git-merge-forward.sh create new test branches:
+# <tbp>_035, <tbp>_040, ... , <tbp>_master, and merge each branch forward into
+# the next one.
 TEST_BRANCH_PREFIX=
 
 while getopts ":hr:st:" opt; do
@@ -200,7 +201,7 @@ PUSH_BRANCHES=$(echo \
 
 if [ -z "$TEST_BRANCH_PREFIX" ]; then
 
-  # maint/release push mode
+  # maint/release push mode: push all branches.
   #
   # List of branches to push. Ordering is not important.
   PUSH_BRANCHES=$(echo \
@@ -212,6 +213,8 @@ if [ -z "$TEST_BRANCH_PREFIX" ]; then
     )
 else
 
+  # Test branch push mode: push test branches, based on each maint branch.
+  #
   # List of branches to push. Ordering is not important.
   PUSH_BRANCHES=" \
     ${TEST_BRANCH_PREFIX}_master \