From 409312d31fd01e1d23ce5d144c8107151d824b4b Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Mon, 3 Sep 2018 11:15:09 +1000
Subject: [PATCH] Add warning job about readthedocs publishing

The readthedocs transition is slightly painful because it requires
readthedocs project owners to add infra to their projects, so we can
not do the update on their behalf.  Not everyone reads the mailing
list, and because the jobs run in the post pipeline it is very easily
missed that the publishing isn't actually happening.

Add a fake, non-voting, always failing job that should attract
attention.  Make a new template which we can switch failing projects
to; which they can easily switch back from in the same change that
adds the extra info required to make the jobs work.

Change-Id: I1866b8b00891caa0e6d9cde99555be8b55792e38
---
 playbooks/docs/rtd-warning-job.yaml |  7 +++++++
 zuul.d/jobs.yaml                    |  8 ++++++++
 zuul.d/project-templates.yaml       | 26 ++++++++++++++++++++++++++
 3 files changed, 41 insertions(+)
 create mode 100644 playbooks/docs/rtd-warning-job.yaml

diff --git a/playbooks/docs/rtd-warning-job.yaml b/playbooks/docs/rtd-warning-job.yaml
new file mode 100644
index 00000000..8feb65e3
--- /dev/null
+++ b/playbooks/docs/rtd-warning-job.yaml
@@ -0,0 +1,7 @@
+- hosts: all
+  tasks:
+    - name: Fail job
+      fail:
+        msg: |
+          Your project requires manual intervention to correctly publish results
+          to readthedocs.  For more details see http://lists.openstack.org/pipermail/openstack-dev/2018-August/132836.html
\ No newline at end of file
diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml
index 1c68fc47..8ef0f1fc 100644
--- a/zuul.d/jobs.yaml
+++ b/zuul.d/jobs.yaml
@@ -262,6 +262,14 @@
     vars:
       constraints_file: '{{ ansible_user_dir }}/src/git.openstack.org/openstack/requirements/upper-constraints.txt'
 
+- job:
+    name: your-readthedocs-job-requires-attention
+    parent: base
+    description: |
+      A placeholder job to warn projects their readthedocs
+      post-pipeline jobs are failing and require updating
+    run: playbooks/docs/rtd-warning-job.yaml
+
 - job:
     name: tox-py35-on-zuul
     parent: tox-py35
diff --git a/zuul.d/project-templates.yaml b/zuul.d/project-templates.yaml
index 0399f23a..ef402c95 100644
--- a/zuul.d/project-templates.yaml
+++ b/zuul.d/project-templates.yaml
@@ -686,6 +686,32 @@
       jobs:
         - trigger-readthedocs-webhook
 
+- project-template:
+    name: docs-on-readthedocs-failing
+    description: |
+      Template for projects requiring updates to their
+      docs-on-readthedocs usage.  Because project managers
+      are required to update their project, infra can not
+      fix deployment.  Since rtd triggering only
+      happens in the post pipeline, nobody really checks the
+      results of the jobs.  Not everyone reads the mailing list as
+      closely as we might like.  The result is a lot of projects
+      with broken documentation publishing that don't know about it.
+
+      This job always fails and provides a link to the mailing list
+      post with details of how to fix the job.
+
+      Revert to docs-on-readthedocs when the webhook id is added to
+      the project.
+    check:
+      jobs:
+        - build-openstack-sphinx-docs
+        - your-readthedocs-job-requires-attention:
+            voting: false
+    gate:
+      jobs:
+        - build-openstack-sphinx-docs
+
 - project-template:
     name: nodejs4-publish-to-npm
     post: