From 4426734823f6754ad6efe6ab50f4de01883fd032 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <lwirzenius@wikimedia.org>
Date: Mon, 20 May 2019 18:28:46 +0300
Subject: Add: clarification and acceptance criterion for UNDERSTANDABLE

---
 ci-arch.html |   2 +-
 ci-arch.mdwn |   6 +++++-
 ci-arch.pdf  | Bin 285565 -> 285787 bytes
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/ci-arch.html b/ci-arch.html
index 36f6d37..71c3195 100644
--- a/ci-arch.html
+++ b/ci-arch.html
@@ -90,7 +90,7 @@
 <p>This is partly due to the <strong>SELFHOSTABLE</strong> requirement, but also because a WMF value is to prefer open source.</p></li>
 </ul></li>
 <li><p><strong>GITSUPPORT</strong> Must support git. We’re not switching version control systems for CI.</p></li>
-<li><p><strong>UNDERSTANDABLE</strong> Must be understandable without too much effort to our developers so that they can use CI/CD productively.</p></li>
+<li><p><strong>UNDERSTANDABLE</strong> Must be understandable without too much effort to our developers so that they can use CI/CD productively. Acceptance critera: our developers can use CI productively, after given a short, 1-page tutorial on how to specify build instructions for their software. FIXME: This might not be very clear.</p></li>
 <li><p><strong>SELFSERVE</strong> Must support self-serve CI, meaning we don’t block people if they want CI for a new repo. Due to <strong>PROTECTPRODUCTION</strong>, there will probably to be some human approval requirement for new projects, but as much as possible, people should be allowed to do their work without having to ask permission.</p>
 <ul>
 <li><strong>SELFSERVE2</strong> Should allow the developers to define or declare at least parts of the pipeline jobs in the repository: what commands to run for building, testing, etc.</li>
diff --git a/ci-arch.mdwn b/ci-arch.mdwn
index 08a5868..4e0bd91 100644
--- a/ci-arch.mdwn
+++ b/ci-arch.mdwn
@@ -137,7 +137,11 @@ future CI system.
   systems for CI.
 
 * **UNDERSTANDABLE** Must be understandable without too much effort to
-  our developers so that they can use CI/CD productively.
+  our developers so that they can use CI/CD productively. Acceptance
+  critera: our developers can use CI productively, after given a
+  short, 1-page tutorial on how to specify build instructions for
+  their software. FIXME: This might not be very clear; suggetions
+  welcome.
 
 * **SELFSERVE** Must support self-serve CI, meaning we don't block
   people if they want CI for a new repo. Due to **PROTECTPRODUCTION**,
diff --git a/ci-arch.pdf b/ci-arch.pdf
index e605a88..09edfad 100644
Binary files a/ci-arch.pdf and b/ci-arch.pdf differ
-- 
cgit v1.2.1