@@ -232,3 +232,104 @@ probably are after a reboot) by looking for processes relating to the
lists flight,job combinations and then:
$ ./mg-hosts previoustasks --clear
+
+
+Flight blessings and the blessed-* host flags
+=============================================
+
+Both flights and hosts have a `blessing'.
+
+Blessings are used:
+
+ * To avoid accidentally tools operating on flights which are in the
+ wrong phase of their existence.
+
+ * To control which automatic archaeologists will look at which
+ flights. (Archeaology tools take arguments to control which
+ blessings they will consider.)
+
+ * To control which hosts are considered suitable for use with which
+ flight. (Flights with blessing `foo' use only hosts which have
+ flag `blessed-foo'.)
+
+Each flight has a `blessing' and an `intended blessing'. The
+`intended blessing' is what the flight is going to be blessed as when
+its execution has completed. The intended blessing controls host
+allocation.
+
+(Normally the `intended blessing' is the same as the bless argument to
+sg-execute-flight aka the -B argument to mg-execute-flight.)
+
+These are the principal (intended) blessings:
+
+ * `real': Flights which are fully production runs. They use only
+ clean working trees with no `funny' environment variables, and
+ versions of osstest intended for production. The data from such
+ flights is used, where applicable, to control production push gate
+ decisions, etc.
+
+ `blessed-real' hosts are fully production-ready.
+
+ * `play': Playground. Flights may use weird software, dirty working
+ trees, strange environment variables, and so on. It does not make
+ sense to point archaeology tools at such flights.
+
+ `blessed-play' hosts may be partially or completely nonfunctional,
+ or strange in some way. For this reason `play' flights should not
+ normally use the automatic host allocator.
+
+ * `adhoc': Special-purpose flights. They should be run with software
+ nearly as clean as `real': the version of the software used may not
+ be a branch intended for-production, but any enhancements or
+ modifications should not leave false or misleading information in
+ the history database.
+
+ `blessed-adhoc' hosts are just as good as `blessed-real' ones.
+
+ The `adhoc' blessing exists mostly to protect the main production
+ workflow from unintentional violations (for example, unexpectedly
+ buggy historical flight data).
+
+ * `commission-<something>': Flights used for testing that a
+ particular subset of the hosts are working properly. The hosts to
+ be tested should be blessed `commission-whatever' during
+ commissioning, and that blessing removed and replaced with `real'
+ when the hosts are ready.
+
+ * `real-bisect' and `adhoc-bisect': These are found only as the
+ blessing of finished flights. (This is achieved by passing *-adhoc
+ to sg-execute-flight.) This allows the archaeologist tools to
+ distinguish full flights from bisection steps.
+
+ The corresponding intended blessing (as found in the `intended'
+ column of the flights table) is `real'. So the hosts used by the
+ automatic host allocator are those flagged `blessed-real' or
+ `blessed-adhoc' - there are no separate blessed-*-bisect hostflags.
+
+There are also blessings for unfinished flights:
+
+ * `constructing': The flight metadata (jobs, runvars, etc.) is still
+ being populated. The tools for flight construction (and flight
+ construct editing) generally insist that they operate only on
+ flights in this state.
+
+ * `running': At least one of the jobs in this flight has started.
+ Flight execution software will generally (perhaps via standard
+ library calls) mark a flight `running' if they find it
+ `constructing', and refuse to operate on other flights.
+
+ * `broken': Something went catastrophically wrong.
+
+Note that osstest is generally `crash-only software': nothing will
+`clean up' a crashed flight and set its blessing to `broken'. Flights
+which were in progress once upon a time but never completed, because
+they crashed, are simply left with whatever blessing they had at the
+time.
+
+There is a special exception to the tools' flight status checks: any
+flight whose blessing contains `play' can be operated on out of order.
+
+Flights blessings can be manually changed with cs-flight-bless. Eg
+ ./cs-flight-bless FLIGHT broken-real real
+updates FLIGHT to be marked `broken' rather than `real'. This can be
+useful if a flight's data is misleading to the archaeologists.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com> --- README.dev | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+)