Document when pre-release upgrade scripts are run

Every time I have to figure out where in the sequence
of upgrade events the per-release within-$base and
from-$base scripts run, I have to dig into the doc.

We have a pretty good document already on the sequence
of phases in a grenade run, but the upgrade section is
pretty fuzzy, and with no mention of when the per-release
scripts run relative to when new code is installed, which
is pretty important if you're going to write one of these
scripts.

So this adds some docs related to when those per-release
upgrade scripts happen relative to installing new code
during the upgrade.

Change-Id: Ic79cd10b2df5fa54a13f73cf49c8f73fa93e9381

PLUGINS.rst

@@ -138,6 +138,24 @@ While create / destroy are only going to be called once in the current
 interface, bonus points for also making those idempotent for
 resiliancy in testing.
 
+**Per-release upgrade scripts**
+
+There are times when :ref:`exceptional <upgrade-exceptions>` manual upgrade
+steps must be performed to get from one release to the next, or even within
+the same release. Grenade supports this with per-release scripts found in
+each project, e.g.::
+
+    projects/
+        60_nova/
+            from-ocata/
+                upgrade-nova
+
+Regarding the sequence of when these per-release scripts are called, any
+``within-$base`` script should be run *before* installing new code, and any
+``from-$base`` script should be run *after* installing new code but before
+starting the services with the new code. This is because configuration or
+database changes may be needed before the upgraded code is started.
+
 Supporting Methods
 ------------------
 

README.rst

@@ -51,6 +51,8 @@ Grenade works under the following theory of upgrade.
   the entire upgrade (whether or not Nova services are up). Taking down
   the control plane should not take down your VMs.
 
+.. _upgrade-exceptions:
+
 - Any other required changes on upgrade are an **exception** and must be
   called out in the release notes.