From 7776b55b4da532710d1ba1792b87153051ac5417 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <lwirzenius@wikimedia.org>
Date: Tue, 7 May 2019 16:22:02 +0300
Subject: Change: fiddle with document structure

---
 ci-arch.html  |  45 ++++++++++++++++++-------------------
 ci-arch.mdwn  |  70 +++++++++++++++++++++++++++++-----------------------------
 ci-arch.pdf   | Bin 286513 -> 285107 bytes
 ecosystem.dot |   1 +
 4 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/ci-arch.html b/ci-arch.html
index 7b4d3fd..52b30ab 100644
--- a/ci-arch.html
+++ b/ci-arch.html
@@ -32,24 +32,23 @@
 <li><a href="#softer-requirements">Softer requirements</a></li>
 <li><a href="#would-be-nice">Would be nice</a></li>
 </ul></li>
-<li><a href="#important-use-cases">Important use cases</a><ul>
+<li><a href="#important-use-cases">Important use cases</a></li>
+<li><a href="#architecture">Architecture</a><ul>
+<li><a href="#the-wmf-development-ecosystem">The WMF development ecosystem</a></li>
 <li><a href="#normal-change-to-an-individual-component">Normal change to an individual component</a></li>
 <li><a href="#interdependent-changes">Interdependent changes</a></li>
 <li><a href="#security-embargoed-change">Security embargoed change</a></li>
-</ul></li>
-<li><a href="#design-of-specific-aspects">Design of specific aspects</a><ul>
 <li><a href="#log-storage">Log storage</a></li>
 <li><a href="#artifact-storage">Artifact storage</a></li>
 <li><a href="#credentials-management-and-access-control">Credentials management and access control</a></li>
 </ul></li>
-<li><a href="#architecture-the-wmf-development-ecosystem">Architecture: The WMF development ecosystem</a></li>
-<li><a href="#the-default-pipeline">The (default?) pipeline</a><ul>
+<li><a href="#the-ci-pipeline">The CI pipeline</a><ul>
 <li><a href="#the-commit-stage">The commit stage</a></li>
 <li><a href="#the-acceptance-stage">The acceptance stage</a></li>
 <li><a href="#manual-tests">Manual tests</a></li>
 <li><a href="#capacity-tests-non-functional-requirements">Capacity tests, non-functional requirements</a></li>
 </ul></li>
-<li><a href="#architecture-internals">Architecture: internals</a></li>
+<li><a href="#ci-implementation">CI implementation</a></li>
 <li><a href="#automated-acceptance-tests-for-ci">Automated acceptance tests for CI</a></li>
 </ul>
 </nav>
@@ -190,6 +189,21 @@
 </ul>
 <h1 id="important-use-cases">Important use cases</h1>
 <p>These are some of the important use cases for the CI system, and how we plan CI to implement them.</p>
+<h1 id="architecture">Architecture</h1>
+<h2 id="the-wmf-development-ecosystem">The WMF development ecosystem</h2>
+<figure>
+<img src="ecosystem.svg" alt="The WMF development ecosystem, roughly" style="height:25.0%" /><figcaption>The WMF development ecosystem, roughly</figcaption>
+</figure>
+<p>The figure above is simplistic, but gives the general idea of what happens when a developer is finished with a change:</p>
+<ol type="1">
+<li>developer pushes a change to Gerrit, which trigger CI</li>
+<li>CI builds and tests change (commit stage)</li>
+<li>CI deploys to a test environment, runs tests against that (acceptance test stage); if everythins is OK, Gerrit is notified and requests code reviews from relevant parties</li>
+<li>testers can request CI it deploy the change to an environment dedicated for manual testing</li>
+<li>after a successful code review, CI merges changes to the master branch, runs all automated tests again, and deploys to the production environment</li>
+</ol>
+<p>The commit and acceptance stages are triggered as soon as developer pushes changes to be reviewed. Human reviews won’t be requested until the two stages pass, as there’s no point in spending human attention on things that are not going to be candidates for deployment to production. The two stages may be re-run after code review, to make sure nothing unforeseen has changed while the review took place.</p>
+<p>Other stages may run in parallel with code review, and if they fail they may nullify the release candidacy of the change. For example, stages for manual and capacity testing, and security test/review; depending on the change and the component in question, some or all of these may be necessary.</p>
 <h2 id="normal-change-to-an-individual-component">Normal change to an individual component</h2>
 <ul>
 <li><p>a developer pushes a change to one program that runs in production</p></li>
@@ -213,7 +227,6 @@
 <li><p>the change will be made public, but CI should be able to use it even before it’s public, so that when it’s time, there’s no need to wait for CI to build/test the change and it can just be merged and deployed</p></li>
 <li><p>this means some builds and builds artifacts need to be locked away from public</p></li>
 </ul>
-<h1 id="design-of-specific-aspects">Design of specific aspects</h1>
 <h2 id="log-storage">Log storage</h2>
 <ul>
 <li><p>We want to capture the build log or “console output” (stdout, stderr) of the build and store it. This is an invaluable tool for developers to understand what happens in a build, and especially why it failed.</p></li>
@@ -244,21 +257,7 @@
 <p>Note that credentials should not come directly from the source code of the deployed program. CI deploys configuration when it deploys the software. This way, the same software (build artifacts) can be deployed to different environment. (This may be complicated by the way MediaWiki is configured, using a PHP file in the source tree. This will need discussion.)</p>
 <p>Tests run against software deployed to containers, and those containers only have access to the backing services needed for the test, and may even be firewalled to not have access to any other network locations.</p>
 <p>Suggestion: Deployments will be done dedicated deployment environments, which run a “pingee” service. When a pipeline executes a deployment stage, deploying to any environment, the stage runs in a suitable container, but doesn’t actually do the deployment itself. Instead, it “pings” a deployment service, with information of who is deploying, what, and where, and the deployment service inspects the change, and if it looks acceptable, does the actual deployment to the desired environment. The deployment service has access to the credentials it needs for accessing the artifacts and doing the deployment. There may be several deployment services, for deploying to environments with different security needs.</p>
-<h1 id="architecture-the-wmf-development-ecosystem">Architecture: The WMF development ecosystem</h1>
-<figure>
-<img src="ecosystem.svg" alt="The WMF development ecosystem, roughly" style="height:25.0%" /><figcaption>The WMF development ecosystem, roughly</figcaption>
-</figure>
-<p>The figure above is simplistic, but gives the general idea of what happens when a developer is finished with a change:</p>
-<ol type="1">
-<li>developer pushes a change to Gerrit, which trigger CI</li>
-<li>CI builds and tests change (commit stage)</li>
-<li>CI deploys to a test environment, runs tests against that (acceptance test stage); if everythins is OK, Gerrit is notified and requests code reviews from relevant parties</li>
-<li>testers can request CI it deploy the change to an environment dedicated for manual testing</li>
-<li>after a successful code review, CI merges changes to the master branch, runs all automated tests again, and deploys to the production environment</li>
-</ol>
-<p>The commit and acceptance stages are triggered as soon as developer pushes changes to be reviewed. Human reviews won’t be requested until the two stages pass, as there’s no point in spending human attention on things that are not going to be candidates for deployment to production. The two stages may be re-run after code review, to make sure nothing unforeseen has changed while the review took place.</p>
-<p>Other stages may run in parallel with code review, and if they fail they may nullify the release candidacy of the change. For example, stages for manual and capacity testing, and security test/review; depending on the change and the component in question, some or all of these may be necessary.</p>
-<h1 id="the-default-pipeline">The (default?) pipeline</h1>
+<h1 id="the-ci-pipeline">The CI pipeline</h1>
 <figure>
 <img src="pipeline.svg" alt="The default pipeline" style="height:25.0%" /><figcaption>The default pipeline</figcaption>
 </figure>
@@ -283,7 +282,7 @@
 <p>This feature of the CI can also be used to demonstrate upcoming features that are not yet ready to be deployed to or enabled in production.</p>
 <h2 id="capacity-tests-non-functional-requirements">Capacity tests, non-functional requirements</h2>
 <p>Capacity tests, and other tests for non-functional requirements, will also be done in dedicated, isolated production-like environments. RelEng will work with the performance team to sort out the details.</p>
-<h1 id="architecture-internals">Architecture: internals</h1>
+<h1 id="ci-implementation">CI implementation</h1>
 <p>FIXME This needs to be written, but it needs a lot of thinking first</p>
 <h1 id="automated-acceptance-tests-for-ci">Automated acceptance tests for CI</h1>
 <ul>
diff --git a/ci-arch.mdwn b/ci-arch.mdwn
index 21b5dcd..f20a30c 100644
--- a/ci-arch.mdwn
+++ b/ci-arch.mdwn
@@ -404,6 +404,39 @@ items.
 These are some of the important use cases for the CI system, and how
 we plan CI to implement them.
 
+# Architecture
+
+## The WMF development ecosystem
+
+![The WMF development ecosystem, roughly](ecosystem.svg){ height=25% }
+
+The figure above is simplistic, but gives the general idea of what
+happens when a developer is finished with a change:
+
+1. developer pushes a change to Gerrit, which trigger CI
+1. CI builds and tests change (commit stage)
+1. CI deploys to a test environment, runs tests against that
+   (acceptance test stage); if everythins is OK, Gerrit is notified
+   and requests code reviews from relevant parties
+1. testers can request CI it deploy the change to an environment
+   dedicated for manual testing
+1. after a successful code review, CI merges changes to the master
+   branch, runs all automated tests again, and deploys to the
+   production environment
+
+The commit and acceptance stages are triggered as soon as developer
+pushes changes to be reviewed. Human reviews won't be requested until
+the two stages pass, as there's no point in spending human attention
+on things that are not going to be candidates for deployment to
+production. The two stages may be re-run after code review, to make
+sure nothing unforeseen has changed while the review took place.
+
+Other stages may run in parallel with code review, and if they fail
+they may nullify the release candidacy of the change. For example,
+stages for manual and capacity testing, and security test/review;
+depending on the change and the component in question, some or all of
+these may be necessary.
+
 ## Normal change to an individual component
 
 * a developer pushes a change to one program that runs in production
@@ -457,8 +490,6 @@ we plan CI to implement them.
 * this means some builds and builds artifacts need to be locked away
   from public
 
-# Design of specific aspects 
-
 ## Log storage
 
 * We want to capture the build log or "console output" (stdout,
@@ -569,38 +600,7 @@ credentials it needs for accessing the artifacts and doing the
 deployment. There may be several deployment services, for deploying to
 environments with different security needs.
 
-# Architecture: The WMF development ecosystem
-
-![The WMF development ecosystem, roughly](ecosystem.svg){ height=25% }
-
-The figure above is simplistic, but gives the general idea of what
-happens when a developer is finished with a change:
-
-1. developer pushes a change to Gerrit, which trigger CI
-1. CI builds and tests change (commit stage)
-1. CI deploys to a test environment, runs tests against that
-   (acceptance test stage); if everythins is OK, Gerrit is notified
-   and requests code reviews from relevant parties
-1. testers can request CI it deploy the change to an environment
-   dedicated for manual testing
-1. after a successful code review, CI merges changes to the master
-   branch, runs all automated tests again, and deploys to the
-   production environment
-
-The commit and acceptance stages are triggered as soon as developer
-pushes changes to be reviewed. Human reviews won't be requested until
-the two stages pass, as there's no point in spending human attention
-on things that are not going to be candidates for deployment to
-production. The two stages may be re-run after code review, to make
-sure nothing unforeseen has changed while the review took place.
-
-Other stages may run in parallel with code review, and if they fail
-they may nullify the release candidacy of the change. For example,
-stages for manual and capacity testing, and security test/review;
-depending on the change and the component in question, some or all of
-these may be necessary.
-
-# The (default?) pipeline
+# The CI pipeline
 
 ![The default pipeline](pipeline.svg){ height=25% }
 
@@ -709,7 +709,7 @@ Capacity tests, and other tests for non-functional requirements, will
 also be done in dedicated, isolated production-like environments.
 RelEng will work with the performance team to sort out the details.
 
-# Architecture: internals
+# CI implementation
 
 FIXME This needs to be written, but it needs a lot of thinking first
 
diff --git a/ci-arch.pdf b/ci-arch.pdf
index 5e609e9..4866384 100644
Binary files a/ci-arch.pdf and b/ci-arch.pdf differ
diff --git a/ecosystem.dot b/ecosystem.dot
index d665132..39d38bb 100644
--- a/ecosystem.dot
+++ b/ecosystem.dot
@@ -8,6 +8,7 @@ digraph ecosystem {
 
         developer -> gerrit;
         gerrit -> developer;
+
         gerrit -> CI;
         CI -> gerrit;
         CI -> autotestenv;
-- 
cgit v1.2.1