Merge pull request #671 from bhearsum/docs

add basic documentation on scriptworker flow of control

Author: bhearsum

docs/flow_of_control.md

@@ -0,0 +1,9 @@
+# Flow of Control
+
+The way a scriptworker runs can be a bit confusing. It involves `scriptworker` itself and its configuration file, a `script` with its own configuration file, multiple processes, and a surprising amount of indirection. The diagram below attempts to show the flow of control. A few things are of special note:
+
+* The initial entrypoint is the `scriptworker` CLI tool.
+* When a Task has been verified, the `script` CLI entry point is run in a subprocess, but that will simply provide `scriptworker.client.sync_main` with a few pieces of data (most notably the `async_main` that actually acts on a Task payload) to continue execution from there. This means that there are two processes that have independently imported `scriptworker` code.
+* Task success or failure is communicated back to the `scriptworker` CLI tool through the return code of the subprocess.
+
+![scriptworker flow of control](flow_of_control.svg)

docs/flow_of_control.mm

@@ -0,0 +1,32 @@
+sequenceDiagram
+	participant init
+	box yellow scriptworker codebase
+	participant s as scriptworker
+	participant sc as scriptworker.client
+	end
+	box green script codebase
+	participant ss as signingscript
+	end
+	init->>s: scriptworker.main
+	rect rgba(243,166,94,255)
+	note left of s: scriptworker process
+	s->>s: read config
+	s->>s: async_main() (polls for tasks)
+	s->>s: execute task
+	s->>s: verify CoT
+	end
+	s->>ss: signingscript.main (in subprocess)
+	rect rgba(169, 226, 235, 255)
+	note left of ss: signingscript process
+	ss->>sc: sync_main(signingscript.async_main, config, ...)
+	sc->>sc: validate config
+	sc->>sc: setup Context
+	sc->>ss: async_main(Context)
+	ss-->>sc: task status
+	end
+	sc-->>s: task status
+	rect rgba(243,166,94,255)
+	note left of s: scriptworker process
+	s->>s: create and sign chain-of-trust.json
+	s->>s: upload artifacts, resolve task
+	end