Merge branch 'master' into 'master'

Add instructions for changing branch names

See merge request !9

howto/gitlab.md

@@ -551,6 +551,57 @@ Untested procedure extracted from the [upstream docs](https://docs.gitlab.com/ee
         sudo gitlab-ctl status
         sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
 
+## Branch Name Changes
+
+Changing the name of a default branch both locally and on remotes can be partially automated with the use of [anarcat's branch rename script](https://gitlab.com/anarcat/scripts/-/blob/main/git-branch-rename-remote). This script performs the following tasks:
+```
+# rename the branch locally if not already done
+git show-ref refs/heads/master > /dev/null && \
+git branch --move master main
+git fetch origin
+# fix HEAD pointer for local remote branch
+git symbolic-ref refs/remotes/remote/HEAD refs/remotes/remote/main
+# push branch remotely if it doesn't exist (or fix tracking branch if it does)
+git branch -u origin/main || exit
+git push -u origin main
+# fix remote HEAD pointer on remote repository
+ssh example.com git symbolic-ref HEAD main
+# delete old branch
+git push -d origin master
+```
+If the `ssh` step fails, it will try to do the equivalent over the GitLab API, that is:
+
+```
+1. unprotect the old branch
+2. protect the new branch
+3. change the default branch
+4. *then* `git push -d` to delete the old branch
+```
+
+However, there are a few extra steps and considerations to make when changing the name of a heavily used branch.
+
+### Modifying open Merge Requests
+
+   A merge request that is open against the modified branch may be bricked as a result of deleting the old branch name from the Gitlab remote. To avoid this, after creating and pushing the new branch name, edit each merge request to target the new branch name **before** deleting the old branch.
+
+### Updating gitolite
+
+Many GitLab repositories are mirrored or maintained manually on gitolite (git-rw.torproject.org) and gitweb (https://git.torproject.org). The `ssh` step for the above automation script will fail for gitolite and these steps need to be done manually by a sysadmin. [Open a TPA ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) with a list of the gitolite repositories you would like to update and a sysadmin will perform the following magic:
+```
+root@cupani:/srv/git.torproject.org/repositories# for repo in [list]; do
+> git -C "$repo" symbolic-ref HEAD refs/heads/[new branch name]
+> done
+```
+
+This will update gitolite, but it won't update gitweb until the repositories have been pushed to. To udpate gitweb immediately, ask your friendly sysadmin to update gitweb manually.
+
+### Updating Transifex
+
+If your repository relies on Transifex for translations, make sure to update the Transifex config to pull from the new branch. To do so, [open a l10n ticket](https://gitlab.torproject.org/tpo/community/l10n/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=) with the new branch name changes.
+
+
+
+
 # Reference
 
 ## Installation