howto/git.md

@@ -312,26 +312,45 @@ although that one doesn't use the proper verb tenses
 This part handles the server side of things. It will install a
 `pre-receive` hook in the Git repository to forbid pushes,
 redirections in the Git web interfaces, and document the change in
-gitolite.
+Gitolite.
 
-It assumes the repository has already been migrated.
+WARNING: it assumes the repository has already been migrated! If you
+are migrating a TPA repository, *do* make sure to first follow the
+above procedure as the procedure below doesn't do anything to actually
+mirror or archive the repository to GitLab (yet).
+
+The procedure is this simple two-step process:
 
  1. (optional) triage the ticket with the labels ~Git and ~Gitweb, and
     the milestone %"legacy Git infrastructure retirement (TPA-RFC-36)"
 
- 4. make an (executable) `pre-receive` hook in `git-rw` with an exit
-    status of `1` warning about the new code location, this can be
-    done with this Fabric command:
+ 2. run the following Fabric task:
+
+        fab -H cupani.torproject.org gitolite.migrate-repo \
+            $GITOLITE_REPO \
+            $GITLAB_PROJECT \
+            --issue-url=$GITLAB_ISSUE
+
+    For example, this is how the `gotlib` project was marked as migrated:
+
+        fab -H cupani.torproject.org gitolite.migrate-repo \
+            pluggable-transports/goptlib \
+            tpo/anti-censorship/pluggable-transports/goptlib \
+            --issue-url=https://gitlab.torproject.org/tpo/tpa/team/-/issues/41182
+
+The following changes are done by the Fabric task:
 
-        fab -H cupani.torproject.org gitolite.migrate-repo pluggable-transports/goptlib tpo/anti-censorship/pluggable-transports/goptlib --issue-url=https://gitlab.torproject.org/tpo/tpa/team/-/issues/41182
+ 1.. make an (executable) `pre-receive` hook in `git-rw` with an exit
+    status of `1` warning about the new code location
 
- 5. in Puppet, add a line for this project in
+ 2. in Puppet, add a line for this project in
     `modules/profile/files/git/gitolite2gitlab.txt` (in
     `tor-puppet.git`), for example:
     
         pluggable-transports/goptlib tpo/anti-censorship/pluggable-transports/goptlib
 
-    the Fabric task should already have done this for you.
+    This ensures proper redirects are deployed on the Gitolite and
+    GitWeb servers.
 
  4. in Gitolite, mark the project as "Migrated to GitLab", for example