From 61ec2f06a0542549495ed0d65feeca23afd4a810 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Bidoul?= <stephane.bidoul@gmail.com>
Date: Sat, 6 Nov 2021 12:15:05 +0100
Subject: [PATCH] Better docs leads to better code

---
 README.md                                     | 19 ++++++++++---------
 src/runboat/k8s.py                            |  2 +-
 .../kubefiles/kustomization.yaml.jinja        |  6 +++---
 src/runboat/models.py                         |  2 +-
 4 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 7e7fc6d..288e960 100644
--- a/README.md
+++ b/README.md
@@ -88,20 +88,21 @@ it more robust. https://bugs.python.org/issue29309
 
 ## Kubernetes resources
 
-All resources to be deployed in kubernetes for a build are in `src/runboat/kubefiles`.
-They are gathered together from a `kustomization.yaml` jinja template that leads to
-three possible resource groups depending on a mode variable in the jinja rendering context:
+All resources to be deployed in kubernetes for a build are in
+[src/runboat/kubefiles](./src/runboat/kubefiles). They are gathered together from a
+`kustomization.yaml` jinja template that leads to three possible resource groups
+depending on a `mode` variable in the jinja rendering context:
 
-- the deployment with its associated service and ingress;
-- the initialization job that creates the database;
-- the cleanup job that drops the database;
+- `deployment` creates a kubernetes deployment with its associated service and ingress;
+- `initialization` creates a job that creates the database;
+- `cleanup` creates a job that drops the database;
 
 Besides the three modes, the controller has limited knowledge of what the kubefiles
 actually deploy. It expects the following to hold true:
 
 - the `runboat/build` label is set on all resources, with the unique build name as
   value;
-- a deployment starts with 0 replicas and must initially have a
+- a deployment starts with 0 replicas and is created with a
   `runboat/init-status=todo` label, as well as a `runboat/cleanup` finalizer;
 - the intialization job has a `runboat/job-kind=initialize` label;
 - the cleanup job has a `runboat/job-kind=cleanup` label.
@@ -116,7 +117,7 @@ During the lifecycle of a build, the controller does the following on the deploy
 resources:
 
 - it sets the `runboat/init-status` annotation (`todo`, `started`, `succeeded`,
-  `failed`) on deployments to track the outcome of the initialization jobs ;
+  `failed`) on deployments to track the outcome of the initialization jobs;
 - it sets the deployment's `specs.replica` to 1 or 0 to start or stop it;
 - it deletes the deployment when an undeploy is requested (the actual delete occurs
   later due to the finalizer);
@@ -125,7 +126,7 @@ resources:
 
 ## TODO
 
-Prototype (min required to open the project):
+Advanced prototype (min required to open the project):
 
 - plug it on a bunch of OCA and shopinvader repos to test load
 
diff --git a/src/runboat/k8s.py b/src/runboat/k8s.py
index 912887b..1500931 100644
--- a/src/runboat/k8s.py
+++ b/src/runboat/k8s.py
@@ -119,7 +119,7 @@ def watch_jobs():
 
 
 class DeploymentMode(str, Enum):
-    deploy = "deploy"
+    deployment = "deployment"
     initialize = "initialize"
     cleanup = "cleanup"
 
diff --git a/src/runboat/kubefiles/kustomization.yaml.jinja b/src/runboat/kubefiles/kustomization.yaml.jinja
index 74ccc52..1983918 100644
--- a/src/runboat/kubefiles/kustomization.yaml.jinja
+++ b/src/runboat/kubefiles/kustomization.yaml.jinja
@@ -1,5 +1,5 @@
 resources:
-  {% if mode == 'deploy' -%}
+  {% if mode == 'deployment' -%}
   - deployment.yaml
   - service.yaml
   - ingress.yaml
@@ -53,7 +53,7 @@ configMapGenerator:
       - runboat-initialize.sh
       - runboat-cleanup.sh
       - runboat-start.sh
-  {% if mode == 'deploy' -%}
+  {% if mode == 'deployment' -%}
   - name: vars
     literals:
       - HOSTNAME={{ hostname }}
@@ -62,7 +62,7 @@ configMapGenerator:
 generatorOptions:
   disableNameSuffixHash: true
 
-{% if mode == 'deploy' -%}
+{% if mode == 'deployment' -%}
 vars:
   - name: HOSTNAME
     objref:
diff --git a/src/runboat/models.py b/src/runboat/models.py
index 6b1e5ef..e61bba8 100644
--- a/src/runboat/models.py
+++ b/src/runboat/models.py
@@ -142,7 +142,7 @@ class Build(BaseModel):
         _logger.info(f"Deploying {slug} ({name}).")
         image = get_build_image(target_branch)
         deployment_vars = k8s.make_deployment_vars(
-            k8s.DeploymentMode.deploy,
+            k8s.DeploymentMode.deployment,
             name,
             slug,
             repo.lower(),