summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBrennen Bearnes <bbearnes@wikimedia.org>2019-05-21 16:47:55 -0600
committerLars Wirzenius <lwirzenius@wikimedia.org>2019-05-22 16:42:06 +0300
commit4ea0fd42dc715f55aacdb7eaca14f8421460a061 (patch)
tree96ba4f8613adc07951dd28040352febb287d5d56
parent4596ce6314bfa88340466e7f405dcd392e0d4ebe (diff)
downloadwmf-ci-arch-4ea0fd42dc715f55aacdb7eaca14f8421460a061.tar.gz
Fix: minor copyedit
An assortment of small fixes to spelling and grammar / phrasing.
-rw-r--r--ci-arch.mdwn74
1 files changed, 37 insertions, 37 deletions
diff --git a/ci-arch.mdwn b/ci-arch.mdwn
index 24c875d..8e48abb 100644
--- a/ci-arch.mdwn
+++ b/ci-arch.mdwn
@@ -1,6 +1,6 @@
---
title: "Thoughts on WMF CI architecture"
-author: Lars Wirzenius, Release Enginering
+author: Lars Wirzenius, Release Engineering
date: WORK IN PROGRESS
abstract: |
The release engineering team is working on replacing the WMF CI
@@ -71,7 +71,7 @@ Kubernetes
This is Lars's personal opinion, for now, but it's based on
discussions with various people while at WMF. It's not expected to be
-new, radical, or controversial, compared to status quo.
+new, radical, or controversial, compared to the status quo.
In the future, CI at WMF serves WMF, its developers, and the Wikipedia
movement by making software development more productive, more
@@ -91,7 +91,7 @@ development.
The overall approach to the architecture of the CI system, and the
workflow supported by it, is to keep all changes in version control
(git), which includes code, configuration, and scripts for building
-and deploying. When a change to version control is pushed, CI builds
+and deploying. When a change is pushed to version control, CI builds
and tests the change, humans review the change, and if all seems to be
in order, CI deploys to production.
@@ -100,7 +100,7 @@ in order, CI deploys to production.
Stakeholders in the WMF CI system include:
* RelEng, who are responsible for keeping CI running
-* SRE, who are responsible for the infrastrcture on which CI runs
+* SRE, who are responsible for the infrastructure on which CI runs
* MediaWiki developers, who develop MW and its extensions, and will
(eventually) be doing MW releases for external MW deployers
* staff and volunteer developers of anything else built, tested, and
@@ -138,7 +138,7 @@ and have been changed a little compared to that (as of the 21 March
## Very hard requirements
-These are non-negotiable requirement that must all be fulfilled by our
+These are non-negotiable requirements that must all be fulfilled by our
future CI system.
* **SELFHOSTABLE** Must be hostable by the Foundation. It's not
@@ -156,7 +156,7 @@ future CI system.
* **UNDERSTANDABLE** 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
+ criteria: 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.
@@ -230,7 +230,7 @@ to a minor degree.
* **GERRIT** Must work with Gerrit as well as other self-hostable
code-review systems (e.g., GitLab), if we decide to move to that
- later. This means, code review happens on Gerrit, after building and
+ later. This means that code review happens on Gerrit, after building and
automated tests pass, and positive code review triggers deployment
to production.
@@ -241,7 +241,7 @@ to a minor degree.
exactly that artifact should be tested, and eventually deployed to
production.
-* **LOCALTESTS** Must allow developer to replicate locally the tests
+* **LOCALTESTS** Must allow a developer to replicate locally the tests
that CI runs. This is necessary to allow lower friction in
development, as well as to aid debugging. For example, if CI builds
and tests using Docker container, a developer should be able to
@@ -252,7 +252,7 @@ to a minor degree.
* **AUTOMATEDSELFDEPLOYMENT** Must be automatically deployable
by us or SRE, onto a fresh server.
- * **DEPLOYCIBUILT** Only build artfifacts built and tested by CI
+ * **DEPLOYCIBUILT** Only build artifacts built and tested by CI
may be deployed to production.
* **HSCALABLE** Must be horizontally scalable: we need to be able to add
@@ -289,9 +289,9 @@ to a minor degree.
which we base our container images.
* **CIMERGES** Must support tooling to do the merging, instead of
- developers. We don't want developer merging by hand and pushing the
+ developers. We don't want developers merging by hand and pushing the
merges. CI should test changes and merge only if tests pass, so that
- the branches for main lines of development are always releaseble.
+ the branches for main lines of development are always releasable.
* **TESTVC** Must support storing tests in version control. This is
probably best achieved by having tests be stored in the same git
@@ -448,7 +448,7 @@ 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
+ (acceptance test stage); if everything 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
@@ -456,11 +456,11 @@ happens when a developer is finished with a change:
branch, runs all automated tests again, and deploys to the
production environment
-The commit and acceptance stages are triggered as soon as developer
+The commit and acceptance stages are triggered as soon as a developer
pushes changes to be reviewed. Human reviews won't be requested
automatically 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. Developer may request reviews of
+for deployment to production. Developers may request reviews of
work-in-progress changes when they want. The two stages may be re-run
after code review, to make sure nothing unforeseen has changed while
the review took place.
@@ -475,17 +475,17 @@ these may be necessary.
* a developer pushes a change to one program that runs in production
-* the change is indepent of other changes and no other component
- depends on the chage
+* the change is independent of other changes and no other component
+ depends on the change
* e.g., bug fix, not a feature change
* the governing principle is that with commit stage and acceptance
stage passing, plus a positive code review, the changes can be
- deploed to to production in most cases
+ deployed to to production in most cases
-* developer pushes change, this trigger commit and acceptance stages,
- which pass, which triggers code review requests to be sent to
+* a developer pushes a change, this triggers commit and acceptance stages,
+ which pass, which in turn triggers code review requests to be sent to
reviewers
* reviewers vote +2, which triggers a deployment to production
@@ -495,7 +495,7 @@ these may be necessary.
## Interdependent changes
* changes to two or more components that must all be applied at once
- or not at all, e.g., to mediawiki core and an extension
+ or not at all, e.g., to MediaWiki core and an extension
* in this scenario the change to MediaWiki core and the change to an
extension may depend on each other, so that if either is deployed
@@ -506,7 +506,7 @@ these may be necessary.
It seems better to be careful with such changes so that they can be
disabled behind a feature flag in the configuration, or by
autodetection of the other component, so that if only one component
- has been changed, it can stillbe deployed. Only when both components
+ has been changed, it can still be deployed. Only when both components
have been changed in production is the feature flag enabled, and the
new feature works.
@@ -521,7 +521,7 @@ these may be necessary.
for CI to build/test the change and it can just be merged and
deployed
-* this means some builds and builds artifacts need to be locked away
+* this means some builds and build artifacts need to be locked away
from public
## Log storage
@@ -546,7 +546,7 @@ these may be necessary.
* Artifacts are all the files created during the build process that
may be needed for automated testing or deployment to production or
- any other environment: executable binaries, minimized Javascript,
+ any other environment: executable binaries, minimized JavaScript,
automatically generated documentation from source code (javadoc).
* We basically need to store arbitrary blobs for some time. We need to
@@ -563,7 +563,7 @@ these may be necessary.
space. Even so, we will want to automatically expire artifacts on
some flexible schedule to keep storage needs in control.
-* We need to decide when we can make these artifacts publically
+* We need to decide when we can make these artifacts publicly
accessible.
* Artifact storage must be secure, as everything that gets deployed to
@@ -626,8 +626,8 @@ 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
+Instead, it "pings" a deployment service, with information on who is
+deploying, what, and where. The deployment service then 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
@@ -644,7 +644,7 @@ that or specify another one.
The pipeline will be divided into several stages. Mandatory stages for
all changes and all projects are commit, acceptance stage, and
deployment to production. Other stages may be added to specific
-changes projects as needed.
+changes or projects as needed.
The goal is that if the commit and acceptance stages pass, the change
is a candidate that can be deployed to production, unless the project
@@ -655,7 +655,7 @@ check those aspects may be required. CI will have ways of indicating
the required changes per component, and also per change. (It is
unclear how this will be managed.)
-If the commit or acceptance stage fails, there is not production
+If the commit or acceptance stage fails, there is not a production
candidate. The pipeline as a whole fails. Any artifacts built by the
pipeline will not be deployable to production, but they may be
deployable to test environments, or downloaded by developers for
@@ -664,7 +664,7 @@ inspection.
## The commit stage
The commit stage builds any deployable artifacts, such as executable
-binaries, minimized Javascript, translation files, or Docker images.
+binaries, minimized JavaScript, translation files, or Docker images.
It is important that artifacts don't get rebuilt by later stages,
because rebuilding does not always result in bitwise identical output.
Instead the goal is to build once, test the artifacts, and deploy the
@@ -672,10 +672,10 @@ tested artifacts, instead of rebuilding and maybe deploying something
different than what was tested.
The commit stage also runs unit tests, and any other tests that can be
-run in isolation from other parts of the system, and that also are
+run in isolation from other parts of the system, and that are also
quick. The commit stage does not have access to backing services, such
as databases or other components of the overall system. For example,
-when the pipeline processes a change to a MediaWiki extenasion, the
+when the pipeline processes a change to a MediaWiki extension, the
commit stage doesn't have access to MediaWiki core or the MariaDB
MediaWiki uses. Integration or system tests should be done in the
acceptance test stage.
@@ -687,7 +687,7 @@ minutes, so that we can expect developers to wait for it to pass
successfully. This will be a new requirement on our developers.
The commands to build (compile) or run automated tests are stored in
-the repository, either explicity, or by indicating the type of build
+the repository, either explicitly, or by indicating the type of build
needed. There might be a `.pipeline/config.yaml` file in the
repository, which specifies that `make` is the command that builds the
artifacts. Otherwise, the file may specify that it's a Go project, and
@@ -700,7 +700,7 @@ as we want control over how that is done (**SECURE** requirement).
CI may enforce specific additional commands to run, to build or test
further things; this can be used by RelEng to enforce certain things.
-For example, we may enforce code health checks, or to enable (or
+For example, we may enforce code health checks, or enable (or
disable) debug symbols in all builds. Such enforcement will be done in
collaboration with our developers.
@@ -709,14 +709,14 @@ specified explicitly. For example, the minimum required version of Go
that should be installed in the build environment would be a build
dependency. If a project build-depends on another project, it needs to
specify which project, and which artifacts it needs installed from the
-other project. Explicit build-dependencies is more work, but results
+other project. Explicit build-dependencies are more work, but result
in fewer problems due to broken heuristics.
## The acceptance stage
During the acceptance stage CI deploys artifacts built in the commit
stage to a production-like system that has the same versions of all
-sofware as production, except for the changes being processed by the
+software as production, except for the changes being processed by the
pipeline. CI will then run automated acceptance tests, and other
integration and system tests, against the deployed software. The test
environment is clean and empty, and well-known, unless and until the
@@ -734,8 +734,8 @@ change to production.
## Manual tests
-Testers may instruct CI to deploy any recent built set of artifacts to
-a dedicated test environment, and can use the software in that
+Testers may instruct CI to deploy any recently built set of artifacts
+to a dedicated test environment, and can use the software in that
environment where it is isolated from others, and won't suddenly
change underneath them. The details of how this will be implemented
are to be determined later.