[libvirt PATCH v2] docs: list settings required in creating a new git repo

[Daniel P. Berrangé]

The libvirt project has alot of git repositories, and they must all be
configured in the same way, more or less. This page documents the
settings changes that I have made in GitLab and GitHub when configuring
projects, both as a reminder for myself, and to help anyone else doing
the same in future. Also included is info about the repo mirroring on
the libvirt.org server.

Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
---

In v2:

 - Apply all Andrea's suggestions

 docs/docs.html.in     |   3 +
 docs/newreposetup.rst | 137 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 docs/newreposetup.rst

diff --git a/docs/docs.html.in b/docs/docs.html.in
index 142c79bfa9..6bdf0c32b8 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -172,6 +172,9 @@
         <dt><a href="testsuites.html">Functional testing</a></dt>
         <dd>Testing libvirt with <a href="testtck.html">TCK test suite</a> and
          <a href="testapi.html">Libvirt-test-API</a></dd>
+
+        <dt><a href="newreposetup.html">New repo setup</a></dt>
+        <dd>Procedure for configuring new git repositories for libvirt</dd>
       </dl>
     </div>
 
diff --git a/docs/newreposetup.rst b/docs/newreposetup.rst
new file mode 100644
index 0000000000..7da13830c0
--- /dev/null
+++ b/docs/newreposetup.rst
@@ -0,0 +1,137 @@
+===============================
+Repository infrastructure setup
+===============================
+
+GitLab Configuration
+====================
+
+The `GitLab organization <https://gitlab.com/libvirt>`_ hosts the master copy
+of all the libvirt Git repositories.
+
+When creating a new repository the following changes to the defaults are
+required under the **Settings** page:
+
+* **General**
+
+  * **Naming, topics, avatar**
+
+    * *Project avatar*: upload ``docs/logos/logo-square-256.png``
+
+  * **Visibility, project features, permissions**
+
+    * *Packages*: disabled
+
+    * *Wiki*: disabled
+
+    * *Snippets*: disabled
+
+  * **Merge Requests**
+
+    * *Merge method*: Fast-forward merge
+
+    * *Merge options*: Enable 'delete source branch' option by default
+
+    * *Merge checks*: Pipelines must succeed
+
+  * **Merge request approvals**
+
+    * *Any eligible user*: Num approvals required == 1
+
+* **Integrations**
+
+  * **Pipelines emails**
+
+    * *Recipients*: ``libvirt-ci at redhat.com``
+
+* **Repository**
+
+  * **Push rules**
+
+    * *Do not allow users to remove git tags with git push*: enabled
+
+    * *Commit message*:  ``Signed-off-by:``
+
+    * *Branch name*: ``^(master|v.*-maint)$``
+
+  * **Mirroring repositories**
+
+    * *Git repository URL*: ``https://libvirtmirror@github.com/libvirt/$repo.git``
+
+    * *Mirror direction*: push
+
+    * *Password*:  see ``/root/libvirt-mirror-github-api-token.txt`` on ``libvirt.org``
+
+  * **Protected branches**
+
+    * *Branch*: ``master``
+
+    * *Allowed to merge*: Developers + Maintainers
+
+    * *Allowed to push*: None (or Developers + Maintainers if MRs not used)
+
+    * *Require approval from code owners*: disabled
+
+GitHub configuration
+====================
+
+The `GitHub organization <https://github.com/libvirt>`_ hosts read-only
+mirrors of all the libvirt Git repositories.
+
+When creating a new repository the following changes to the defaults are
+required under the **Settings** page:
+
+* **Options**
+
+  * **Features**
+
+    * *Wikis*: disabled
+
+    * *Sponsorships*: disabled
+
+    * *Projects*: disabled
+
+  * **Manage access**
+
+    * Add the ``@committers`` team with the role "Write", which
+      grants ``libvirtmirror`` access to sync from gitlab.
+
+  * **Integrations**
+
+    * Check for *Repo Lockdown*  (should be set automatically for all projects)
+
+In the master git repository create a file `.github/lockdown.yml` to restrict
+use of issue tracker and pull requests.
+
+
+libvirt.org
+===========
+
+The `libvirt project server <https://libvirt.org>`_ hosts read-only mirrors of
+all the libvirt Git repositories in the directory ``/data/git``.
+
+When creating a new repository the following steps are required:
+
+* Create repo with
+  ::
+
+     $ sudo su -
+     # cd /data/git
+     # mkdir $repo.git
+     # cd $repo.git
+     # git init --bare
+     # touch export
+     # touch git-daemon-export-ok
+     # cd ..
+     # chown -R gitmirror.gitmirror $repo.git
+     # chmod -R g+w $repo.git
+     # find -type d $repo.git | xargs chmod g+s
+
+* Set the ``description`` and ``config`` files following other repos' example
+
+* Setup mirroring
+  ::
+
+    $ sudo su - gitmirror
+    # ./newrepo.sh /data/git/$repo.git
+    # cd mirrors
+    # $HOME/sync-one.sh $repo.git
-- 
2.24.1