Update changelog, add upgrading to 3.0 section to docs

CHANGES.md

@@ -1,10 +1,14 @@
 ### 3.0.0
 
-* New internal architecture
-* Significant performance improvements and memory efficiency
-* New ES6 Promise shim
-* New `when.try` and `when.lift`
-* New [liftAll] for lifting all of an object's functions in one go, eg. `var promisedFs = node.liftAll(require('fs'))`
+* New internal architecture with significant performance improvements and memory efficiency
+* New APIs
+	* [`when.try`](docs/api.md#whentry), [`when.lift`](docs/api.md#whenlift), [`when.reduceRight`](docs/api.md#whenreduceRight), [`when.iterate`](docs/api.md#wheniterate), [`when.unfold`](docs/api.md#whenunfold), [`when.race`](docs/api.md#whenrace)
+	* [`promise.with`](docs/api.md#promisewith), [`promise.else`](docs/api.md#promiseelse), [`promise.delay`](docs/api.md#promisedelay), [`promise.timeout`](docs/api.md#promisetimeout), [`promise.progress`](docs/api.md#promiseprogress)
+* New liftAll variants for lifting all of an object's functions in one shot, eg. `var promisedFs = node.liftAll(require('fs'))`
+	* [`fn.liftAll`](docs/api.md#fnliftall), [`node.liftAll`](docs/api.md#nodeliftall), [`callbacks.liftAll`](docs/api.md#callbacksliftall)
+* `when.Promise` public, inheritance-friendly, Promise constructor
+* New [ES6 Promise shim](docs/es6-promise-shim.md)
+* Check out the [tips for upgrading to 3.0 from 2.x](#upgrading-to-30-from-2x)
 
 ### 2.8.0
 

docs/api.md

@@ -73,6 +73,7 @@ API
 	* [when/guard(condition, f)](#whenguard)
 	* [Guard conditions](#guard-conditions)
 1. [Debugging promises](#debugging-promises)
+1. [Upgrading to 3.0 from 2.x](#upgrading-to-30-from-2x)
 
 # Core
 
@@ -1831,3 +1832,27 @@ Currently, PrettyMonitor is compatible with when 2.x, and will be updated to wor
 ## Roll your own!
 
 The monitor modules are building blocks.  The [when/monitor/console](../monitor/console.js) module is one particular, and fairly simple, monitor built using the monitoring APIs and tools (PrettyMonitor is another, prettier one!).  Using when/monitor/console as an example, you can build your own promise monitoring tools that look for specific types of errors, or patterns and log or display them in whatever way you need.
+
+# Upgrading to 3.0 from 2.x
+
+While there have been significant architectural changes in 3.0, it remains almost fully backward compatible.  There are a few things that were deprecated and have now been removed, and functionality that has moved to a new preferred spot.
+
+## Backward incompatible changes
+
+Previously deprecated features that have been removed in 3.0:
+
+* `promise.always` was removed. Use [`promise.finally(cleanup)`](#promisefinally) (or its ES3 alias [`promise.ensure`](#promisefinally), or [`promise.then(cleanup, cleanup)`](#promisethen) instead.
+* `deferred.resolve`, `deferred.reject`, `deferred.resolver.resolve`, and `deferred.resolver.reject` no longer return promises. They always return `undefined`.  You can simply return `d.promise` instead if you need.
+* [`when.all`](#whenall), [`when.any`](#whenany), and [`when.some`](#whensome) no longer directly accept `onFulfilled`, `onRejected`, and `onProgress` callbacks.  Simply use the returned promise instead.
+	* For example, do this: `when.all(array).then(handleResults)` instead of this: `when(array, handleResults)`
+* `when.isPromise` was removed. Use [`when.isPromiseLike`](#whenispromiselike) instead.
+
+## Moved functionality
+
+Some functionality has moved to a new, preferred API.  The old APIs still work, and were left in place for backward compatibility, but will eventually be removed:
+
+* `when/delay` module. Use [`promise.delay`](#promisedelay) instead.
+* `when/timeout` module. Use [`promise.delay`](#promisedelay) instead.
+* `when/node/function` module. Use the [`when/node`](#node-style-asynchronous-functions) module instead.
+* `when/unfold` and `when/unfold/list` modules. Use [`when.unfold`](#whenunfold) instead
+* `when/function` `lift` and `call`. Use [`when.lift`](#whenlift) and [`when.try`](#whentry) instead.