docs: describe more of what I did

Sponsored-by: author

1 files changed, 105 insertions, 1 deletions

diff --git a/README.md b/README.md
index fef3cee..43aef68 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,9 @@
 This is the work sample for my job application for a developer
 position for OSO.
 
+This document explains the work I've done and verifies that the code I
+wrote works together with the client.
+
 ## Re-statement of problem
 
 To clarify the problem for myself, I am re-stating it. This will also
@@ -167,6 +170,8 @@ one it has found so far.
 * The list in the client doesn't change during the computation: items
   stay in the same order, and are not added, deleted, or changed.
 
+* The client responds truthfully.
+
 # Remarks
 
 * Given the list the client has is unordered, O(n) comparisons is the
@@ -174,7 +179,7 @@ one it has found so far.
   algorithms are possible. If list can be ordered, a binary search
   would be optimal.
 
-# Acceptance criteria
+# Acceptance criteria {#acceptnace}
 
 ## Find max of a list of one
 
@@ -246,6 +251,105 @@ when I run max-client.py 7 6 5
 then answer is 7
 ~~~
 
+# What I did
+
+## The client
+
+I modified slightly the `max-client.py` file:
+
+* it is now an executable Python script, and formatted with Black
+* the user can invoke it with a list of numbers, and tell it whether
+  to ask the server to find the min or the max number
+
+I made these changes so that I could use it when verifying the
+acceptance criteria defined in this document. The original code tested
+only two cases, which I found to be inadequate for my purposes.
+
+The Python code is not entirely to current Python best practices. For
+example, it doesn't use type annotations. I have not started using
+those yet: at work I've only used old versions of Python that don't
+support type annotations, and in my free time, I don't write anything
+of significant size in Python anymore.
+
+## The server
+
+The server is in `server.py`, and is a Python program using
+`bottle.py`. I chose Python, because for something small and simple
+like this it's easy. I chose `bottle.py` because it's familiar for me.
+
+I could have chosen Rust, and probably the `warp` crate for the HTTP
+API, but it would have required much more implementation work, and
+probably more than is warranted for this exercise.
+
+The code is a little simplistic in that it doesn't do much in terms of
+error handling, logging, or such. At the same time it's overly
+complicated, because I wanted to make sure it allows for more than
+just the "max" algorithm. "min" is implemented, and the same structure
+should be usable for, say, finding the second largest element. More
+interesting algorithms would require changes to the messages: if, for
+example, one wanted the server to find out if the list is ordered, the
+"done" message would need to be able to express the result.
+
+## The testing
+
+I have used the [Subplot](https://subplot.liw.fi/) program to verify
+that my server works. Subplot documents the acceptance criteria and
+how they are verified. That is this document. The section [Acceptance
+criteria](#acceptance) documents the acceptance criteria using
+_scenarios_ consisting of given/when/then steps.
+
+Subplot produces two typeset documents (one in HTML, one in PDF), and
+a self-standing test program, which can be run to verify the system
+under test fulfills the acceptance criteria. To avoid requiring you to
+have Subplot installed, the test program is included in the git
+repository as `test.py`. You can run it like this:
+
+~~~sh
+$ python3 test.py --log test.log
+srcdir /home/liw/pers/oso/work-sample
+datadir /tmp/tmpcom39rm7
+scenario: Find max of a list of one
+  step: given server
+  step: when I run max-client.py 1
+  step: then answer is 1
+  cleanup: given server
+scenario: Find max of a list of two
+  step: given server
+  step: when I run max-client.py 5 5
+  step: then answer is 5
+  step: when I run max-client.py 5 6
+  step: then answer is 6
+  step: when I run max-client.py 6 5
+  step: then answer is 6
+  cleanup: given server
+scenario: Find max of a list of three
+  step: given server
+  step: when I run max-client.py 5 5 5
+  step: then answer is 5
+  step: when I run max-client.py 5 5 6
+  step: then answer is 6
+  step: when I run max-client.py 5 6 5
+  step: then answer is 6
+  step: when I run max-client.py 6 5 5
+  step: then answer is 6
+  step: when I run max-client.py 5 6 7
+  step: then answer is 7
+  step: when I run max-client.py 5 7 6
+  step: then answer is 7
+  step: when I run max-client.py 6 5 7
+  step: then answer is 7
+  step: when I run max-client.py 6 7 5
+  step: then answer is 7
+  step: when I run max-client.py 7 5 6
+  step: then answer is 7
+  step: when I run max-client.py 7 6 5
+  step: then answer is 7
+  cleanup: given server
+OK, all scenarios finished successfully
+$
+~~~
+
+I hope that is satisfactory.
 
 ---
 title: "OSO work sample—MAX"