gerrit: Add helpful comments to various configuration files

This hopefully makes the definitions for gerrit.baserock.org more easy
for others to adapt.

6 files changed, 49 insertions, 2 deletions

diff --git a/baserock_gerrit/All-Projects/project.config b/baserock_gerrit/All-Projects/project.config
index 0b16b280..acf859d2 100644
--- a/baserock_gerrit/All-Projects/project.config
+++ b/baserock_gerrit/All-Projects/project.config
@@ -9,6 +9,9 @@
 #   https://gerrit-documentation.storage.googleapis.com/Documentation/2.11/access-control.html
 #   https://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source/gerrit.rst
 
+# To deploy changes to this file, you need to manually commit it and push it to
+# the 'refs/meta/config' ref of the All-Projects repo in Gerrit.
+
 [project]
 	description = Access inherited by all other projects.
 
diff --git a/baserock_gerrit/baserock_gerrit.morph b/baserock_gerrit/baserock_gerrit.morph
index cf93af22..76a92667 100644
--- a/baserock_gerrit/baserock_gerrit.morph
+++ b/baserock_gerrit/baserock_gerrit.morph
@@ -1,11 +1,25 @@
 name: baserock_gerrit
 kind: cluster
+
+description: |
+  Deployment .morph for baserock.org Gerrit system.
+
+  Configuration of the system is handled separately, with a series of
+  Ansible playbooks that should be run after an instance of the system
+  is up and running. See the README for instructions.
+
 systems:
   - morph: systems/gerrit-system-x86_64.morph
     deploy:
       gerrit.baserock.org:
         type: openstack
         location: https://compute.datacentred.io:5000/v2.0
+
+        # You can use this method to deploy upgrades over SSH, after the
+        # machine is deployed.
+        #type: ssh-rsync
+        #location: root@gerrit.baserock.org
+
         OPENSTACK_IMAGENAME: baserock_gerrit
         CLOUD_INIT: yes
         DISK_SIZE: 3G
diff --git a/baserock_gerrit/gerrit-access-config.yml b/baserock_gerrit/gerrit-access-config.yml
index d17df33e..3966c928 100644
--- a/baserock_gerrit/gerrit-access-config.yml
+++ b/baserock_gerrit/gerrit-access-config.yml
@@ -7,8 +7,18 @@
 # These modules depend on pygerrit:
 #
 #   https://www.github.com/sonyxperiadev/pygerrit/
-
-#   -
+#
+# If you want to change the configuration, just edit this script and rerun it,
+# as described in the README.
+#
+# This script currently doesn't handle committing changes to the access control
+# rules for the 'All-Projects' project. To set up or modify the access control
+# rules, you'll need to manually commit project.config (in the All-Projects
+# subdirectory) to the 'refs/meta/config' ref of the All-Projects repo in
+# Gerrit. The 'groups' file will need to list all the groups referenced in
+# project.config. This script will add the UUIDs of all groups listed below
+# to the All-Projects/groups file, so you don't have to create it manually.
+---
 - hosts: localhost
   tasks:
     # System groups:
diff --git a/baserock_gerrit/gerrit.config b/baserock_gerrit/gerrit.config
index d0d7c57d..f8e0bc95 100644
--- a/baserock_gerrit/gerrit.config
+++ b/baserock_gerrit/gerrit.config
@@ -1,3 +1,7 @@
+# This is the main Gerrit configuration. If you make changes to this
+# file, rerun `ansible-playbook -i hosts baserock_gerrit/instance-config.yml`
+# to deploy them to production.
+
 [gerrit]
 	basePath = git
 	canonicalWebUrl = http://gerrit.baserock.org/
diff --git a/baserock_gerrit/instance-mirroring-config.yml b/baserock_gerrit/instance-mirroring-config.yml
index a0130d22..bcf1c90d 100644
--- a/baserock_gerrit/instance-mirroring-config.yml
+++ b/baserock_gerrit/instance-mirroring-config.yml
@@ -1,3 +1,16 @@
+# This Ansible playbook configures mirroring in and out of Gerrit.
+#
+# To run it, use:
+#   ansible-playbook -i hosts baserock_gerrit/instance-mirroring-config.yml
+#
+# It expects the SSH key for the 'lorry' user to exist at
+# ../keys/lorry-gerrit.key.
+#
+# This script currently doesn't handle the lorry-controller.conf file that
+# controls what lorry-controller mirrors into Gerrit. To set up or modify
+# lorry-controller configuration you need to commit your changes to the
+# 'local-config/lorries' project on the Gerrit.
+---
 - hosts: gerrit
   gather_facts: no
   sudo: yes
diff --git a/baserock_gerrit/replication.config b/baserock_gerrit/replication.config
index fab59c14..067acc9b 100644
--- a/baserock_gerrit/replication.config
+++ b/baserock_gerrit/replication.config
@@ -1,6 +1,9 @@
 # Configuration for gerrit-replication plugin.
 #
 # This handles pushing changes from gerrit.baserock.org to git.baserock.org.
+#
+# To deploy changes in this file to production, run:
+#   ansible-playbook -i hosts baserock_gerrit/instance-mirroring-config.yml
 
 [remote "trove"]
   url = ssh://git@git.baserock.org/${name}.git