From 892215e27f5e85219296e5da72f34b8c79080929 Mon Sep 17 00:00:00 2001
From: Joel Dudley <joel.dudley@r3cev.com>
Date: Thu, 9 Aug 2018 11:46:14 +0100
Subject: [PATCH] Clarification in upgrade docs. (#3759)

* Clarification in upgrade docs.

* Address review comments.
---
 docs/source/upgrading-cordapps.rst | 37 ++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/docs/source/upgrading-cordapps.rst b/docs/source/upgrading-cordapps.rst
index 33ed24ce85..ff87949cfd 100644
--- a/docs/source/upgrading-cordapps.rst
+++ b/docs/source/upgrading-cordapps.rst
@@ -278,8 +278,8 @@ participants agree to the proposed upgrade. The following combinations of upgrad
 * A state is upgraded while the contract stays the same
 * The state and the contract are updated simultaneously
 
-Performing contract and state upgrades
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Performing explicit contract and state upgrades
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 1. Preserve the existing state and contract definitions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -325,25 +325,38 @@ For example, in case of hash constraints the hash of the legacy JAR file should
 
 3. Create the new CorDapp JAR
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Produce a new CorDapp JAR file and distribute it to all the relevant nodes. This JAR file should contain all the old
-contract and state definitions, plus any new contract and state definitions.
+Produce a new CorDapp JAR file. This JAR file should only contain the new contract and state definitions.
 
-4. Restart the nodes
+4. Distribute the new CorDapp JAR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Place the new CorDapp JAR file in the ``cordapps`` folder of all the relevant nodes. You can do this while the nodes are still 
+running.
+
+5. Stop the nodes
+^^^^^^^^^^^^^^^^^
+Have each node operator stop their node. If you are also changing flow definitions, you should perform a 
+:ref:`node drain <draining_the_node>` first to avoid the definition of states or contracts changing whilst a flow is 
+in progress.
+
+6. Re-run the network bootstrapper
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you're using the network bootstrapper instead of a network map server and have defined any new contracts, you need to 
+re-run the network bootstrapper to whitelist the new contracts. See :doc:`network-bootstrapper`.
+
+7. Restart the nodes
 ^^^^^^^^^^^^^^^^^^^^
-Have each node operator stop their node, replace the existing CorDapp JAR with the new CorDapp JAR, and restart their
-node. They may wish to do a :ref:`node drain <draining_the_node>` first to avoid the definition of states or contracts
-changing whilst a flow is in progress.
+Have each node operator restart their node.
 
-5. Authorise the upgrade
+8. Authorise the upgrade
 ^^^^^^^^^^^^^^^^^^^^^^^^
-Once the new states and contracts are on the classpath for all the relevant nodes, the nodes must all run the
+Now that new states and contracts are on the classpath for all the relevant nodes, the nodes must all run the
 ``ContractUpgradeFlow.Authorise`` flow. This flow takes a ``StateAndRef`` of the state to update as well as a reference
 to the new contract, which must implement the ``UpgradedContract`` interface.
 
 At any point, a node administrator may de-authorise a contract upgrade by running the
 ``ContractUpgradeFlow.Deauthorise`` flow.
 
-6. Perform the upgrade
+9. Perform the upgrade
 ^^^^^^^^^^^^^^^^^^^^^^
 Once all nodes have performed the authorisation process, a **single** node must initiate the upgrade via the
 ``ContractUpgradeFlow.Initiate`` flow for each state object. This flow has the following signature:
@@ -626,4 +639,4 @@ Writing enums
 Elements cannot be added to enums in a new version of the code. Hence, enums are only a good fit for genuinely static
 data that will never change (e.g. days of the week). A ``Buy`` or ``Sell`` flag is another. However, something like
 ``Trade Type`` or ``Currency Code`` will likely change. For those, it is preferable to choose another representation,
-such as a string.
\ No newline at end of file
+such as a string.