Normalize semaphore branch handling
We already had some protection for duplicate semaphore definitions:
we would simply ignore all but the first.
Normalize this to the recently changed behavior for secrets and nodes:
ignore duplicate definitions on different branches of the same project,
but otherwise, do not allow them.
This is more agressive configuration validation in some cases -- folks
with existing duplicate semaphore definitions will now encounter errors.
We also perform more validation of semaphores for proposed config updates.
We still don't use the new values, however, we do verify that the change
won't cause any config parse errors or duplicate errors.
Change-Id: I61b43fa1d1e67c35ab5653f35a7667138ed25aa2
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 3f3a412..7fdf96e 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -1301,9 +1301,19 @@
represents the maximum number of jobs which use that semaphore at the
same time.
+Semaphores, like most configuration items, are globally unique, though
+a semaphore may be defined on multiple branches of the same project as
+long as the value is the same. This is to aid in branch maintenance,
+so that creating a new branch based on an existing branch will not
+immediately produce a configuration error.
+
Semaphores are never subject to dynamic reconfiguration. If the value
of a semaphore is changed, it will take effect only when the change
-where it is updated is merged. An example follows:
+where it is updated is merged. However, Zuul will attempt to validate
+the configuration of semaphores in proposed updates, even if they
+aren't used.
+
+An example usage of semaphores follows:
.. code-block:: yaml