diff --git a/docs/upstream-updates/index.rst b/docs/upstream-updates/index.rst
new file mode 100644
index 0000000..52099e6
--- /dev/null
+++ b/docs/upstream-updates/index.rst
@@ -0,0 +1,66 @@
+Upstream Updates
+================
+
+Updating the facade and definitions code generated from the schema
+to reflect changes in upstream Juju consists of two steps:
+
+* Creating a new `schemas-juju-<version>.json` file from the Juju code-base
+* Generating the libjuju Python code from that schema
+
+Rarely, you may also have to add or update an override.
+
+
+Creating a Schema File
+----------------------
+
+First, you will need to fetch SchemaGen_ and a copy of the Juju source.
+Once your copy of the Juju source is at the version you want to update to
+(probably the `develop` branch, or a release tag) and you have updated
+and reinstalled SchemaGen to reflect those changes, you just need to send
+the output into a file in the libjuju repository:
+
+.. code:: bash
+
+  schemagen > juju/client/schemas-juju-2.2-rc1.json
+
+The version number you use in the filename should match the upstream
+version of Juju.  You should then also move the `latest` pointer to
+the new file:
+
+.. code:: bash
+
+  rm juju/client/schemas-juju-latest.json
+  ln -s schemas-juju-2.2-rc1.json juju/client/schemas-juju-latest.json
+
+
+Generating the Python Code
+--------------------------
+
+Once you have a new schema file, you can update the Python code
+using the `client` make target:
+
+.. code:: bash
+
+  make client
+
+You should expect to see updates to the `juju/client/_definitions.py` file,
+as well as one or more of the `juju/client/_clientX.py` files, depending on
+which facades were touched.
+
+
+Overrides
+---------
+
+It should be quite rare, but occasionally the generated Python code does
+not capture all of the logic needed to properly parse the output from the API
+or may otherwise need some small amount of tweaking.  This is what the
+`juju/client/overrides.py` file is for.  An example of this is the `Number`
+type, which isn't standard JSON and must be parsed slightly differently.
+
+At the top of that file are two lists, `__all__` and `__patches__`.  The
+former replaces entire class implementations, while the latter patches
+the attributes of the override classes into the matching generated class,
+leaving the rest of the generated class untouched.
+
+
+.. _SchemaGen: https://github.com/juju/schemagen