The rationale is that (eventually? hopefully?) that documentation will
be irrelevant as all repos will have been migrated.

In general, we put migration docs in the *source* service, not the
target, because of that reason.

We keep the heading and a link to avoid breaking links.

howto/git.md

@@ -240,7 +240,106 @@ Changes to most repositories are reported to:
 
  * Some repositories have a dedicated mailing list for commits at https://lists.torproject.org
 
-### GitHub and GitLab Mirrors
+### How to migrate a Git repository from legacy to GitLab?
+
+Important: this policy is still being debated. It is not clear if any
+or all repositories should be migrated to GitLab, see [issue 36][]
+for the discussion on this topic.
+
+As an example of a repository migration, I have moved the wiki from
+gitolite to gitlab just now. I have followed the following procedure:
+
+ 1. import the Gitolite repository in GitLab:
+ 
+    * [create a new project](https://gitlab.torproject.org/projects/new)
+    * pick the "Import project" button
+    * pick the "Repo by URL" button
+    * copy-paste the `https://git.torproject.org/...` Git Repository
+      URL
+    * pick a project name and namespace (should ideally match the
+      original project as close as possible)
+    * add a description (again, matching the original from
+      gitweb/gitolite)
+    * pick the "Create project" button
+ 
+    This will import the git repository into a new GitLab project.
+
+ 3. if the repository is to be archived on GitLab, make it so in
+    `Settings` -> `General` -> `Advanced` -> `Archive project`
+
+ 4. make an (executable) `pre-receive` hook in `git-rw` with an exit
+    status of `1` warning about the new code location, example:
+
+        $ cat /srv/git.torproject.org/repositories/project/help/wiki.git/hooks/pre-receive 
+        #!/bin/sh
+
+        cat <<EOF
+        This repository has been migrated to GitLab:
+
+        https://gitlab.torproject.org/tpo/tpa/services/-/wikis/home
+
+        Update your remotes to:
+
+            git@gitlab.torproject.org:tpo/tpa/services.wiki.git
+
+        or:
+
+            https://gitlab.torproject.org/tpo/tpa/services.wiki.git
+
+        See this issue for details:
+
+        https://gitlab.torproject.org/tpo/tpa/services/-/issues/34437
+        EOF
+
+        exit 1
+
+    or in the case of a fully archived repository (non-writable):
+    
+        $ cat /srv/git.torproject.org/repositories/project/help/infra.git/hooks/pre-receive 
+        #!/bin/sh
+
+        cat <<EOF
+        This repository has been migrated to GitLab:
+
+        https://gitlab.torproject.org/tpo/tpa/wiki-infra-archive
+
+        We have migrated away from ikiwiki so it is not necessary anymore.
+
+        See this issue for details:
+
+        https://gitlab.torproject.org/tpo/tpa/services/-/issues/34437
+        EOF
+
+        exit 1
+
+ 4. in Gitolite, make the project part of the "Attic", for example
+
+        @@ -328,13 +328,13 @@ admin/trac/TracAccountManager "The Tor Project" = "Tor specific changes to Matth
+         
+         repo project/help/infra
+             RW+                                      = @torproject-admin
+        -    config gitweb.category                   = Infrastructure and Administration
+        -project/help/infra "The Tor Project" = "help.torproject.org infrastructure"
+        +    config gitweb.category                   = Attic
+        +project/help/infra "The Tor Project" = "help.torproject.org infrastructure (archived to GitLab: https://gitlab.torproject.org/tpo/tpa/wiki-infra-archive')"
+         
+         repo project/help/wiki
+             RW                                       = anarcat
+        -    config gitweb.category                   = Infrastructure and Administration
+        -project/help/wiki "The Tor Project" = "help.torproject.org content"
+        +    config gitweb.category                   = Attic
+        +project/help/wiki "The Tor Project" = "help.torproject.org content (archived to GitLab: https://gitlab.torproject.org/tpo/tpa/wiki-archive')"
+         
+         repo project/jenkins/jobs
+             RW                                       = @jenkins-admins
+
+The only downside with that approach is that a git clone will not warn
+about the project redirection, but I am not sure there's a way to fix
+that.
+
+See [issue 36][] for further discussion.
+
+### GitHub and GitLab Mirrors implementation details
 
 Some repositories are mirrored to https://github.com/torproject
 organization and to the https://gitlab.torproject.org/ server, through