95de087 docs: use want/why/who for acceptance criteria — radicle-ci-broker

Radicle CI broker

docs: use want/why/who for acceptance criteria

Lars Wirzenius committed 1 year ago

commit 95de0878de2556e207f306649f5b9b7c53653533
parent d69be6f457b663dca4288a98bf5e2802b4ae0ce3

1 file changed +59 -59

modified ci-broker.md

@@ -176,13 +176,13 @@ rad id list

 ## Shows config as JSON
 _Requirement:_ The CI broker can write out the configuration is uses
 _Want:_ The CI broker can write out the configuration is uses
 at run time as JSON.
 _Justification:_ This is helpful for the node operator to verify that
 _Why:_ This is helpful for the node operator to verify that
 they have configured the program correctly.
 _Stakeholder:_ Lars
 _Who:_ Lars
 Our verification here is quite simplistic, and only checks that the
 output is in the JSON format. It does not try to make sure the JSON

@@ -199,12 +199,12 @@ then command is successful

 ## Smoke test: Runs adapter
 _Requirement:_ CI broker can run its adapter.
 _Want:_ CI broker can run its adapter.
 _Justification:_ This is obviously necessary. If this doesn't work,
 _Why:_ This is obviously necessary. If this doesn't work,
 nothing else has a hope of working.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -236,10 +236,10 @@ then stdout contains "id: "xyzzy""

 ## Adapter can provide URL for info on run
 _Requirement:_ The adapter can provide a URL for information about the
 _Want:_ The adapter can provide a URL for information about the
 run, such a run log. This optional.
 _Justification:_ The CI broker does not itself store the run log, but
 _Why:_ The CI broker does not itself store the run log, but
 it's useful to be able to point users at one. The CI broker can put
 that into a Radicle COB or otherwise store it so that users can see
 it. Note, however, that the adapter gets to decide which URL to

@@ -247,7 +247,7 @@ provide: it need not be the run log. It might, for example, be a URL

 to the web view of a "pipeline" in GitLab CI instead, from which the
 user can access individual logs.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -280,14 +280,14 @@ echo '{"response":"finished","result":"success"}'

 ## Gives helpful error message if node socket can't be found
 _Requirement:_ If the CI broker can't connect to the Radicle node
 _Want:_ If the CI broker can't connect to the Radicle node
 control socket, it gives an error message that helps the user to
 understand the problem.
 _Justification:_ This helps users deal with problems themselves and
 _Why:_ This helps users deal with problems themselves and
 reduces the support burden on the Radicle project.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -304,14 +304,14 @@ then stderr contains "node control socket does not exist: xyzzy.sock"

 ## Gives helpful error message if it doesn't understand its configuration file
 _Requirement:_ If the CI broker is given a configuration file that it
 _Want:_ If the CI broker is given a configuration file that it
 can't understand, it gives an error message that explains the problem
 to the user.
 _Justification:_ This helps users deal with problems themselves and
 _Why:_ This helps users deal with problems themselves and
 reduces the support burden on the Radicle project.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 _Comment:_ This is a very basic scenario. Error handling is by nature
 a thing that can always be made better. We can later add more

@@ -337,15 +337,15 @@ This file is not YAML.

 ## Stops if the node connection breaks
 _Requirement:_ If the connection to the Radicle node, via its control
 _Want:_ If the connection to the Radicle node, via its control
 socket, breaks, the CI broker terminates with a message saying why.
 _Justification:_ The CI broker can either keep running and trying to
 _Why:_ The CI broker can either keep running and trying to
 re-connect, or it can terminate. Either is workable. However, it's a
 simpler design and less code to terminate and allow re-starting to be
 handled by a dedicated system, such as `systemd`.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -363,13 +363,13 @@ then command is successful

 ## Shuts down when requested
 _Requirement:_ The test suite can request the CI broker to shut down
 _Want:_ The test suite can request the CI broker to shut down
 cleanly, and it doesn't result in an error.
 _Justification:_ In the integration test suite, we need to start and
 _Why:_ In the integration test suite, we need to start and
 stop the CI broker many times. We need to easily detect errors.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 We use a special magic fake node event to signal shutdown: a
 `RefsFetched` event with a skipped update for a ref "`shutdown`" and

@@ -395,12 +395,12 @@ then stdout is exactly ""

 ## Produces a report page upon request
 _Requirement:_ The node operator can run a command to produce a report
 _Want:_ The node operator can run a command to produce a report
 of all CI runs a CI broker instance has performed.
 _Justification:_ This is useful for diagnosis, if nothing else.
 _Why:_ This is useful for diagnosis, if nothing else.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -428,13 +428,13 @@ a controlled fashion.

 ## Dummy adapter runs successfully
 _Requirement:_ The dummy adapter (in embedded file `dummy.sh`) runs
 _Want:_ The dummy adapter (in embedded file `dummy.sh`) runs
 successfully.
 _Justification:_ Test scenarios using the dummy adapter need to be
 _Why:_ Test scenarios using the dummy adapter need to be
 able to rely that it works.
 _Stakeholder:_ Lars
 _Who:_ Lars
 ~~~scenario
 given file dummy.sh

@@ -445,13 +445,13 @@ then command is successful

 ## Adapter with URL runs successfully
 _Requirement:_ The adapter with a URL (in embedded file
 _Want:_ The adapter with a URL (in embedded file
 `adapter-with-url.sh`) runs successfully.
 _Justification:_ Test scenarios using this adapter need to be able to
 _Why:_ Test scenarios using this adapter need to be able to
 rely that it works.
 _Stakeholder:_ Lars
 _Who:_ Lars
 ~~~scenario
 given file adapter-with-url.sh

@@ -462,13 +462,13 @@ then command is successful

 ## Event synthesizer terminates after first connection
 _Requirement:_ The event synthesizer runs in the background, but
 _Want:_ The event synthesizer runs in the background, but
 terminates after the first connection.
 _Justification:_ This is needed so that it can be invoked in Subplot
 _Why:_ This is needed so that it can be invoked in Subplot
 scenarios.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 The following scenario may only work on Linux, as it's using `pgrep`
 and `nc` and those may not be portable. If so, this may need to be

@@ -511,13 +511,13 @@ every value is set exactly once.

 ## Count in a single process
 _Requirement:_ A single process can increment the test counter
 _Want:_ A single process can increment the test counter
 correctly.
 _Justification:_ If this doesn't work with a single process, it won't
 _Why:_ If this doesn't work with a single process, it won't
 work of multiple processes, either.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given an installed cibtool

@@ -532,14 +532,14 @@ then stdout is exactly "1000\n"

 ## Insert events into queue
 _Requirement:_ Insert broker events generated from node events into
 _Want:_ Insert broker events generated from node events into
 persistent event queue in the database, when allowed by the CI broker
 event filter.
 _Justification:_ This is fundamental for running CI when repositories
 _Why:_ This is fundamental for running CI when repositories
 in a node change.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -564,11 +564,11 @@ then stdout contains "old: Some(Oid(0000000000000000000000000000000000000000))"

 ## Insert many events into queue
 _Requirement:_ Insert many events that arrive quickly.
 _Want:_ Insert many events that arrive quickly.
 _Justification:_ We need at least some rudimentary performance testing.
 _Why:_ We need at least some rudimentary performance testing.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -592,13 +592,13 @@ then stdout is exactly "1000\n"

 ## Don't insert events into queue when not allowed by filter
 _Requirement:_ Nothing is inserted into the persistent event queue
 _Want:_ Nothing is inserted into the persistent event queue
 then the CI broker's filter does not allow any events.
 _Justification:_ This is fundamental for running CI when repositories
 _Why:_ This is fundamental for running CI when repositories
 in a node change.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given file radenv.sh

@@ -621,10 +621,10 @@ then stdout is exactly "0\n"

 ## Process queued events
 _Requirement:_ It's possible to run the CI broker in a mode where it
 _Want:_ It's possible to run the CI broker in a mode where it
 only processes events from its persistent event queue.
 _Justification:_ This is primarily useful for testing the CI broker
 _Why:_ This is primarily useful for testing the CI broker
 queuing implementation.
 _Stakeholders:_ Lars.

@@ -664,13 +664,13 @@ then stdout contains "Success"

 ## Count in concurrent processes
 _Requirement:_ Two process can concurrently increment the test counter
 _Want:_ Two process can concurrently increment the test counter
 correctly.
 _Justification:_ This is necessary, if not necessarily sufficient, for
 _Why:_ This is necessary, if not necessarily sufficient, for
 concurrent database use to work correctly.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 Due to limitations in Subplot we mange the concurrent processes using
 a helper shell script,k `count.sh`, found below. It runs two

@@ -749,13 +749,13 @@ queue.

 ## Events can be queued and removed from queue
 _Requirement:_ `cibtool` can show the queued events, can inject an
 _Want:_ `cibtool` can show the queued events, can inject an
 event, and remove an event.
 _Justification:_ This is the minimum functionality needed to manage
 _Why:_ This is the minimum functionality needed to manage
 the event queue.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 We verify that this works by adding a new broker event, and then
 removing it. We randomly choose the repository id for the CI broker

@@ -786,13 +786,13 @@ then stdout is exactly ""

 ## Can add shutdown event to queue
 _Requirement:_ `cibtool` can add a shutdown event to the queued
 _Want:_ `cibtool` can add a shutdown event to the queued
 events.
 _Justification:_ This is needed for testing, and for the node operator
 _Why:_ This is needed for testing, and for the node operator
 to be able to do this cleanly.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given an installed cibtool

@@ -806,12 +806,12 @@ then stdout contains "Shutdown"

 ~~~
 ## Add CI run information to database
 _Requirement:_ `cibtool` can add information about a CI run, possibly
 _Want:_ `cibtool` can add information about a CI run, possibly
 one that is imaginary.
 _Justification:_ This is primarily needed for testing.
 _Why:_ This is primarily needed for testing.
 _Stakeholder:_ Lars.
 _Who:_ Lars.
 ~~~scenario
 given an installed cibtool