This adds support for the "queued" status in github checks. This allows
users to configure an "enqueue" reporter to set the "queued" status on
a check for a github PR. Since the "start" reporter doesn't change the
status of a check until Zuul starts to run jobs, this can be used to
provide near-immediate feedback to users that a change has been enqueued
into a pipeline. If the change remains outside the active window for
some time, the "queued" status can be useful to let users know that
future work is pending.
The reference gate pipeline for github is updated to include
an "enqueue" reporter, as well as a reporter for both "dequeue" and
"no-jobs". These two, along with "success" and "failure", cover all
of the ways a change may exit a pipeline and will therefore finalize
the check with a completed result (so that it is not left in a pending
state in the github web UI).
Some minor changes are made to the reference pipelines for consistent
formatting.
The docs are updated not only to add the new status keyword, but also
to switch to using the "value" tag in the "zuul" sphinx domain. This
allows us to link to the individual values.
To ensure that we don't report "dequeue" in cases where we have not
reported anything yet, we add an additional flag to the queue item to
storte whether we have reported "enqueue". This is initialized in
the constructor, so it will be set for currently existing objects
without the need for an explicit upgrade path.
The code that sets the reported_start flag is updated slightly so that
both reported_start and reported_enqueue are used the same way.
Change-Id: I99653a0b31d26724e1728e3e8368015a11f73bff
a738d00fb9