7ddb877 doc: format with Subplot, improve text — radicle-ci-broker

modified doc/Makefile

@@ -1,7 +1,7 @@

 .SUFFIXES: .uml .svg .dot .pik .md .html
 .SUFFIXES: .uml .svg .dot .pik .md .html .subplot
 .md.html:
 	pandoc -V date="Version: $$(git describe --long --dirty --all)" --toc --number-sections --standalone --self-contained $< -o $@
 .subplot.html:
 	subplot docgen --date "Version: $$(git describe --long --dirty)" $< -o $@
 .dot.svg:
 	dot -Tsvg $< > $@.tmp

@@ -19,7 +19,7 @@ all: architecture.html userguide.html

 publish: all
 	bash publish.sh
 architecture.html: architecture.svg architecture-ext.svg comp.svg comp-ext.svg Makefile
 architecture.html: architecture.subplot architecture.md Makefile
 userguide.html: userguide.subplot userguide.md Makefile
 	subplot docgen $< --output $@

deleted doc/architecture-ext.uml

@@ -1,13 +0,0 @@

 @startuml
 node -> broker : RefsFetched event
 broker -> adapter : spawn
 broker -> adapter : send request
 adapter-> engine : trigger run
 engine -> worker : start run
 note over worker : perform the run
 engine -> adapter : response with run id
 adapter -> broker : response: run id
 worker -> engine : run finished
 engine -> adapter : web hook?
 adapter -> broker : response: result
 @enduml

modified doc/architecture.md

@@ -1,13 +1,12 @@

 ---
 title: Radicle CI architecture
 author: The Radicle Team
 ...
 # Overview
 [Radicle](https://radicle.xyz/) is a peer-to-peer collaboration system
 built on top of the git version control system. Radicle has support
 for integrating with continuous integration (CI) systems, using an
 [Radicle]: https://radicle.xyz/
 [Git]: https://git-scm.com/
 [CI]: https://en.wikipedia.org/wiki/Continuous_integration
 [Radicle] is a peer-to-peer collaboration system
 built on top of the [Git] version control system. Radicle has support
 for integrating with continuous integration ([CI]) systems, using an
 architecture where a "broker" listens to events about changes to
 repositories stored in a node, and launching the appropriate "adapter"
 for each change, according to its configuration.

@@ -17,10 +16,10 @@ changes according to the interests of the person whose node it is.

 * The delegates for a repository might run CI on all patches to make
   merge decisions with more confidences.
 * Someone whose contributing to a project might only care about
 * Someone else, who is contributing to a project, might only care about
   patches they themselves created, and only run CI for those.
 * A third party might run CI for projects they use, to know if it's OK
   to deploy to production.
   to deploy to their production systems.
 Radicle provides its own, very simple "native CI" solution. It's just
 good enough for the Radicle project to use itself. In addition, there

@@ -37,9 +36,31 @@ they are:

 These all run on the same host.
 ![Components for native CI](comp.svg)
 ~~~dot
 digraph "" {
    radicle_node [label="Radicle node"];
    broker [label="CI broker"];
    native [label="Native CI"];
    commands [label="Shell commands \n from .radicle/native.yaml"];
    radicle_node -> broker [label="change event"];
    broker -> native [label="invoke"];
    native -> commands [label="run"];
    native -> broker [label="result"];
 }
 ~~~
 ~~~plantuml
 @startuml
 node -> broker : RefsFetched event
 broker -> adapter : spawn
 broker -> adapter : send request
 adapter -> broker : response: run id
 note over adapter : perform the run
 adapter -> broker : response: result
 @enduml
 ~~~
 ![Sequence diagram for native CI](architecture.svg)
 ## Components when integrating an external CI system

@@ -54,10 +75,25 @@ The first three of these run on the same host, but the external CI

 instance can run anywhere. The adapter talks to the CI instance using
 whatever protocol the CI instance supports, such as HTTP.
 ~~~dot
 digraph "" {
    radicle_node [label="Radicle node"];
    broker [label="CI broker"];
    adapter [label="Adapter"];
    engine [label="External CI system"];
    radicle_node -> broker [label="change event"];
    broker -> adapter [label="invoke"];
    adapter -> engine [label="run"];
    engine -> adapter [label="web hook?"];
    adapter -> broker [label="result"];
 }
 ~~~
 External CI integration works like this:
 * a repository known to the node changes
   - a git ref is updated
   - a Git ref is updated
   - the ref can be a branch, tag, or something else, such as a Radicle
     COB
   - the node emits an event describing the change

@@ -68,7 +104,7 @@ External CI integration works like this:

   configuration for the repository involved
 * for an event that passes its filters, the CI broker spawns the
   appropriate adapter process
   - there are different adapter for different CI implementations
   - there is a different adapter for each different CI implementation
 * the broker sends a request object to the adapter as a child process,
   via the child's stdin, and reads any responses from the child's
   stdout

@@ -81,9 +117,21 @@ External CI integration works like this:

   - it may involve the CI instance making a web hook request back to
     the adapter
 ![Components for external CI](comp-ext.svg)
 ![Sequence diagram for external CI](architecture-ext.svg)
 ~~~plantuml
 @startuml
 node -> broker : RefsFetched event
 broker -> adapter : spawn
 broker -> adapter : send request
 adapter-> engine : trigger run
 engine -> worker : start run
 note over worker : perform the run
 engine -> adapter : response with run id
 adapter -> broker : response: run id
 worker -> engine : run finished
 engine -> adapter : web hook?
 adapter -> broker : response: result
 @enduml
 ~~~
 # The adapter

@@ -301,22 +349,14 @@ previous message.

 The CI broker has an SQLite database file for persistent storage of
 information of the CI runs it triggers. This is used to generate
 report pages.
 The report pages are HTML, generated from the information in the
 database. The broker loads information for all runs when it starts,
 from the database, and then pushed information about new runs when
 they happen. This avoids the broker having to read everything every
 time it updates the report pages.
 report pages, among other things.
 The report page generation is done in its own thread, separate from
 the main thread of the CI broker. This allows the reporting to happens
 independently of what the main thread is doing. In particular, it
 means the main thread does not need to do anything to trigger reports
 from being updated.
 When it comes to per-run logs, for external CI these are kept by the
 external CI instance and the broker never sees them. For native CI,
 the native CI adapter writes them to the report directory, as
 `$RUNID/log.html`, and the broker generates report pages that link to
 those files.
 means the report generation happens even while the main thread is busy
 running an adapter.
 When it comes to per-run logs, the adapter can include a URL to one in
 the first response message. The URL will be included as a link in the
 report HTML.

added doc/architecture.subplot

@@ -0,0 +1,8 @@

 title: "Radicle CI broker"
 subtitle: Architecture
 authors:
   - The Radicle Project
 markdowns:
   - architecture.md
 classes:
   - json

deleted doc/architecture.uml

@@ -1,8 +0,0 @@

 @startuml
 node -> broker : RefsFetched event
 broker -> adapter : spawn
 broker -> adapter : send request
 adapter -> broker : response: run id
 note over adapter : perform the run
 adapter -> broker : response: result
 @enduml

deleted doc/comp-ext.dot

@@ -1,12 +0,0 @@

 digraph "" {
    radicle_node [label="Radicle node"];
    broker [label="CI broker"];
    adapter [label="Adapter"];
    engine [label="External CI system"];
    radicle_node -> broker [label="change event"];
    broker -> adapter [label="invoke"];
    adapter -> engine [label="run"];
    engine -> adapter [label="web hook?"];
    adapter -> broker [label="result"];
 }
 \ No newline at end of file

deleted doc/comp.dot

@@ -1,11 +0,0 @@

 digraph "" {
    radicle_node [label="Radicle node"];
    broker [label="CI broker"];
    native [label="Native CI"];
    commands [label="Shell commands"];
    radicle_node -> broker [label="change event"];
    broker -> native [label="invoke"];
    native -> commands [label="run"];
    native -> broker [label="result"];
 }
 \ No newline at end of file