Add an upgrading document

This outlines our baseline assumptions regarding upgrading.

Change-Id: I2f63b3b3d643fc2aae4f35de8206d4081afa1494

2 files changed, 46 insertions, 0 deletions

diff --git a/doc/source/admin.rst b/doc/source/admin.rst
index c7e2431f5..f77889bec 100644
--- a/doc/source/admin.rst
+++ b/doc/source/admin.rst
@@ -5,6 +5,7 @@ Service Administration
    :maxdepth: 2
 
    installation
+   upgrading
    components
    configuration
    drivers/index
diff --git a/doc/source/upgrading.rst b/doc/source/upgrading.rst
new file mode 100644
index 000000000..8282efc37
--- /dev/null
+++ b/doc/source/upgrading.rst
@@ -0,0 +1,45 @@
+Upgrading
+=========
+
+Rolling Upgrades
+----------------
+
+If more than one of each Zuul component is present in a system, then
+Zuul may be upgrading without downtime by performing a rolling
+upgrade.  During a rolling upgrade, components are stopped and started
+one at a time until all components are upgraded.  If there is a
+behavior change during an upgrade, Zuul will typically wait until all
+components are upgraded before changing behavior, but in some cases
+when it is deemed safe, new behaviors may start to appear as soon as
+the first component is upgraded.  Be sure not to begin using or rely
+on new behaviors until all components are upgraded.
+
+Unless specified in the release notes, there is no specific order for
+which components should be upgraded first, but the following order is
+likely to produce the least disruption and delay the use of new
+behaviors until closer to the end of the process:
+
+* Gracefully restart executors (one at a time, or as many as a
+  system's over-allocation of resources will allow).
+* Gracefully restart mergers.
+* Restart schedulers.
+* Restart web and finger gateways.
+
+Skipping Versions
+-----------------
+
+Zuul versions are specified as `major.minor.micro`.  In general,
+skipping minor or micro versions during upgrades is considered safe.
+Skipping major versions is not recommended, as backwards compatibility
+code for older systems may be removed during a major upgrade.  This
+means that, for example, an upgrade from 5.x.y to 7.0.0 should include
+at least an upgrade to 6.4.0 (the latest 6.x release) before
+proceeding to 7.0.0.
+
+If skipping major versions is required, then a rolling upgrade is not
+possible, and Zuul should be completely stopped, and the ``zuul-admin
+delete-state`` command should be run before restarting on the new
+version.
+
+Some versions may have unique upgrade requirements.  See release notes
+for additional information about specific version upgrades.