Support submitWholeTopic in Gerrit

This adds a query for changes which are set (by Gerrit) to be submitted
together due to submitWholeTopic being enabled.  In this case, changes
which are of the same topic will be merged simultaneously by Gerrit,
therefore Zuul should treat them as a set of circular dependencies.

The behavior is automatic, since Gerrit will return a set of changes
if the setting is enabled, or the empty list if it is not.  Zuul still
requires that circular dependencies be enabled in any queues where they
appear.

If users have submitWholeTopic enabled in Gerrit but do not have
allow-circular-dependencies enabled, they may begin to see errors.
However, the errors are self-explanatory, and installations such as
these are already not testing what Gerrit will merge, so reporting
the discrepancy is an improvement.

Change-Id: Icf65913a049a9b9ddbedd20cc73bf44ffcc831b8

1 files changed, 14 insertions, 13 deletions

diff --git a/doc/source/config/queue.rst b/doc/source/config/queue.rst
index bc24bb4fb..c18bf8939 100644
--- a/doc/source/config/queue.rst
+++ b/doc/source/config/queue.rst
@@ -46,30 +46,31 @@ Here is an example ``queue`` configuration.
    .. attr:: allow-circular-dependencies
       :default: false
 
-      Define if Zuul is allowed to process circular dependencies between
-      changes for this queue. All projects that are part of a dependency cycle
-      must share the same change queue.
+      Determines whether Zuul is allowed to process circular
+      dependencies between changes for this queue. All projects that
+      are part of a dependency cycle must share the same change queue.
 
-      In case Zuul detects a dependency cycle it will make sure that every
-      change also includes all other changes that are part of the cycle.
-      However each change will still be a normal item in the queue with its own
-      jobs.
+      If Zuul detects a dependency cycle it will ensure that every
+      change also includes all other changes that are part of the
+      cycle.  However each change will still be a normal item in the
+      queue with its own jobs.
 
       Reporting of success will be postponed until all items in the cycle
-      succeeded. In case of a failure in any of those items the whole cycle
+      succeed. In the case of a failure in any of those items the whole cycle
       will be dequeued.
 
-      An error message will be posted to all items of the cycle in case some
+      An error message will be posted to all items of the cycle if some
       items fail to report (e.g. merge failure when some items were already
       merged). In this case the target branch(es) might be in a broken state.
 
       In general, circular dependencies are considered to be an
       antipattern since they add extra constraints to continuous
       deployment systems.  Additionally, due to the lack of atomicity
-      in merge operations in code review systems, it may be possible
-      for only part of a cycle to be merged.  In that case, manual
-      interventions (such as reverting a commit, or bypassing gating to
-      force-merge the remaining commits) may be required.
+      in merge operations in code review systems (this includes
+      Gerrit, even with submitWholeTopic set), it may be possible for
+      only part of a cycle to be merged.  In that case, manual
+      interventions (such as reverting a commit, or bypassing gating
+      to force-merge the remaining commits) may be required.
 
       .. warning:: If the remote system is able to merge the first but
                    unable to merge the second or later change in a