diff --git a/docs/source/upgrading-cordapps.rst b/docs/source/upgrading-cordapps.rst
index 6b28ec1fd9..5e519a20d3 100644
--- a/docs/source/upgrading-cordapps.rst
+++ b/docs/source/upgrading-cordapps.rst
@@ -641,3 +641,29 @@ Although not strictly related to versioning, AMQP serialisation dictates that we
   wildcard
 * Any superclass must adhere to the same rules, but can be abstract
 * Object graph cycles are not supported, so an object cannot refer to itself, directly or indirectly
+
+
+Testing CorDapp upgrades
+------------------------
+
+At the time of this writing there is no platform support to test CorDapp upgrades. There are plans to add support in a future version.
+This means that it is not possible to write automated tests using just the provided tooling.
+
+To test an implicit upgrade, you must simulate a network that initially has only nodes with the old version of the CorDapp, and then nodes gradually transition to the new version.
+Typically, in such a complex upgrade scenario, there must be a deadline by which time all nodes that want to continue to use the CorDapp must upgrade.
+To achieve this, this deadline must be configured in the flow logic which must only use new features afterwards.
+
+This can be simulated with a scenario like this:
+
+1. Write and individually test the new version of the state and contract.
+2. Setup a network of nodes with the previous version. In the simplest form, `deployNodes` can be used for this purpose.
+3. Run some transactions between nodes.
+4. Upgrade a couple of nodes to the new version of the CorDapp.
+5. Continue running transactions between various combinations of versions. Also make sure transactions that were created between nodes with the new version
+are being successfully read by nodes with the old CorDapp.
+6. Upgrade all nodes and simulate the deadline expiration.
+7. Make sure old transactions can be consumed, and new features are successfully used in new transactions.
+
+
+
+