diff --git a/doc/upgrading-contracts.md b/doc/upgrading-contracts.md
new file mode 100644
index 000000000..fdac0f960
--- /dev/null
+++ b/doc/upgrading-contracts.md
@@ -0,0 +1,30 @@
+# How to upgrade contracts
+
+At least initially, we retain the ability to upgrade the nightfall contracts following deployment.
+We use the Openzeppelin [Upgrades](https://docs.openzeppelin.com/upgrades-plugins/1.x/) Truffle plugin
+to do that.  Make sure you have read the details before attempting an upgrade because there are some
+specifics around the structure of the contract that need to be addressed.
+
+## The approach
+
+We use `deployer` to upgrade contracts. `deployer` has 4 migrations stored in its migration folder
+The first three migrations perform a 'normal' deployment of the polygon-nightfall contract suite. They
+do however make sure that all contracts (but not libraries) are deployed with a proxy to enable them to
+be upgraded at a later date. The fourth migration is used to upgrade contracts.
+
+In a normal deployment run, `deployer` will only run the first three migrations. If, however, its
+`UPGRADE` environment variable is set to <anything at all>, then the first three migrations will be ignored
+and the subsequent migrations run. Currently that's only migration 4.
+
+The upgrade migration (4) requires editing to include the contracts that you wish to upgrade (unless they have
+the same name as the original contracts). Then, running deployer will result in the contracts being upgraded.
+
+Don't forget that the solidity source code is contained within the `deployer` container. Therefore, it is necessary
+to rebuild the container to incorporate any changes to the contract code.
+
+Note that libraries are not proxied. They contain no state, and so we freely re-deploy and re-link them each time.
+It may be cheaper to proxy them but this adds significantly to the number of proxy contracts.
+
+## Testing
+
+Please see the README in the ping-pong test directory.