From 18bf4494f76e52492000e8b3eacbfd0d7baf71a9 Mon Sep 17 00:00:00 2001
From: "James E. Blair" <jeblair@redhat.com>
Date: Sun, 15 Oct 2017 18:25:32 -0700
Subject: [PATCH] Document base job change procedure

Change-Id: Ie7266a6f948d28211426a9a9d7ce0865168a65a8
---
 zuul.d/jobs.yaml | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml
index 0078db2675..202bf53ab1 100644
--- a/zuul.d/jobs.yaml
+++ b/zuul.d/jobs.yaml
@@ -2,6 +2,27 @@
 # Contains definitions of trusted jobs
 # Overrides jobs from:
 #    https://git.openstack.org/cgit/openstack-infra/zuul-jobs
+
+
+# Changes to this job require a special procedure, because they can
+# not be tested before landing, and if they are faulty, they will
+# break all jobs, meaning subsequent corrections will not be able to
+# land.  To make a change:
+#
+# 1) Ensure that base-test and its playbooks are identical to base.
+# 2) Make the change to base-test and/or its playbooks.
+# 3) Merge the change from step 2.  No jobs normally use base-test, so
+#    this is safe.
+# 4) Propose a change to a job to reparent it to base-test.  Choose a
+#    job which will exercise whatever you are changing.  The
+#    "unittests" job in zuul-jobs is a good choice.  Use [DNM] in the
+#    commit subject so that people know not to merge the change.  Set
+#    it to "Work in progress" so people don't review it.
+# 5) Once test results arrive for the change in step 2, make a change
+#    which copies the job and/or playbooks of base-test to base.  In
+#    the commit message, link to (without using Depends-On:) the
+#    change from step 4 so reviewers can see the test results.
+# 6) Once the change in step 5 merges, abandon the change from step 4.
 - job:
     name: base
     parent: null
@@ -62,6 +83,8 @@
     secrets:
       - site_logs
 
+# See the procedure described above "base" before making changes to
+# this job.
 - job:
     name: base-test
     parent: null