Add api version upgrade info

ChangeLog.md

@@ -1,14 +1,16 @@
 #Change Log
 
-The page contains a quick summary of every version of the API
+The page contains a quick summary of every version of the API.
 
-##v1.1.0
+Versions listed on this page are considered stable and should not change. For information about upcoming versions and features see the [Roadmap](roadmap/README.md)
+
+##API Version 1.1.0
 
 * Visual Host Addtions
     * **createSelectionIdBuilder** - allows for creation of unique identifiers used for data selection
     * **createSelectionManager** - manages the selection state of the visual and communicates changes to the visual host
     * **colors** - an array of default colors to use in your visual
 
-##v1.0.0
+##API Version v1.0.0
 
 * Initial API release

tools/usage.md

@@ -55,7 +55,7 @@ Once your server is started, you will see the default template as your visual.
 
 -----------
 
-##Packaging your Visual for distribution
+##Packaging your visual for distribution
 
 Before you can load your visual into [PowerBI Desktop](https://powerbi.microsoft.com/en-us/desktop/) or share it with the community in the [PowerBI Visual Gallery](https://visuals.powerbi.com) you'll need to generate a `pbiviz` file.
 
@@ -69,6 +69,47 @@ This command will create a pbiviz file in the `dist/` directory of your visual p
 
 -----------
 
+##Updating visuals API 
+
+When you create a visual using `pbiviz new` a copy of the appropriate api type definitions and json schemas is copied into your visual directory. You can use the `pbiviz update` command to update these files if needed. This can be useful if we release a fix for a past API version or if you want to update to the latest API version.
+
+####Updating your existing API version
+
+If we release an update to an existing API you can get the latest version by doing the following.  
+
+```bash
+
+#Update your version of pbiviz
+npm install -g powerbi-visuals-tools
+
+#Run update from the root of your visual project (where pbiviz.json is located)
+pbiviz update
+
+```
+
+This will download the latest tools from npm (which includes the updated type definitions and schemas) and `pbiviz update` will overwrite the version in your visual with the latest version. This will maintain the api version your visual already uses (specified in your pbiviz.json file).
+
+####Upgrading to a different API version
+
+You can update to a different api version by using the same steps, but explicitly specifying an API version in the update command.
+
+```bash
+
+#Update your version of pbiviz
+npm install -g powerbi-visuals-tools
+
+#Run update from the root of your visual project (where pbiviz.json is located)
+pbiviz update 1.2.0
+
+```
+
+This would update your visual to api version 1.2.0 (replace 1.2.0 with whatever version you're trying to upgrade to).
+
+> **API VERSION WARNING**
+> The default API version used by the tools will always be the stable version of the API. Any later versions are unstable, subject to change, and may behave differently in different environments (service vs desktop). For the current stable API version see the [Change Log](../ChangeLog.md) for information about pre-release versions see the [Roadmap](../Roadmap/README.md)
+
+-----------
+
 ##Troubleshooting