Create v2 Migration document

Readme.md

@@ -80,7 +80,7 @@ app.use((ctx, next) => {
 
 ### GeneratorFunction
 
-To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co) that is no longer supplied with Koa.
+To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co).
 
 ```js
 app.use(co.wrap(function *(ctx, next) {
@@ -91,35 +91,13 @@ app.use(co.wrap(function *(ctx, next) {
 }));
 ```
 
-### Old signature middleware (v1.x) - Deprecated
+### KOA v1.x Middleware Signature
 
-**Old signature middleware (v1.x) support will be removed in v3**
+The middleware signature changed between v1.x and v2.x. The older signature is deprecated.
 
-Koa v2.x will try to convert legacy signature, generator middleware on `app.use`, using [koa-convert](https://github.com/koajs/convert).
-It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
+**Old signature middleware support will be removed in v3**
 
-```js
-// Koa will convert
-app.use(function *(next) {
- const start = new Date();
- yield next;
- const ms = new Date() - start;
- console.log(`${this.method} ${this.url} - ${ms}ms`);
-});
-```
-
-You could do it manually as well, in which case Koa will not convert.
-
-```js
-const convert = require('koa-convert');
-
-app.use(convert(function *(next) {
- const start = new Date();
- yield next;
- const ms = new Date() - start;
- console.log(`${this.method} ${this.url} - ${ms}ms`);
-}));
-```
+Please see the [Migration Guide](docs/migration.md) for more information on upgrading from v1.x.
 
 ## Babel setup
 

docs/migration.md

@@ -0,0 +1,115 @@
+# Migrating from Koa v1.x to v2.x
+
+## New Middleware Signature 
+
+Koa v2 introduces a new signature for middleware.
+
+**Old signature middleware (v1.x) support will be removed in v3**
+
+The new middleware signature is:
+
+```js
+// uses async arrow functions
+app.use(async (ctx, next) => {
+ try {
+ await next() // next is now a function
+ } catch (err) {
+ ctx.body = { message: err.message }
+ ctx.status = err.status || 500
+ }
+})
+
+app.use(async ctx => {
+ const user = await User.getById(this.session.userid) // await instead of yield
+ ctx.body = user // ctx instead of this
+})
+```
+
+You don't have to use asynchronous functions - you just have to pass a function that returns a promise. 
+A regular function that returns a promise works too!
+
+The signature has changed to pass `Context` via an explicit parameter, `ctx` above, instead of via
+`this`. The context passing change makes koa more compatible with es6 arrow functions, which capture `this`.
+
+## Using v1.x Middleware in v2.x
+
+Koa v2.x will try to convert legacy signature, generator middleware on `app.use`, using [koa-convert](https://github.com/koajs/convert).
+It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
+
+```js
+// Koa will convert
+app.use(function *(next) {
+ const start = new Date();
+ yield next;
+ const ms = new Date() - start;
+ console.log(`${this.method} ${this.url} - ${ms}ms`);
+});
+```
+
+You could do it manually as well, in which case Koa will not convert.
+
+```js
+const convert = require('koa-convert');
+
+app.use(convert(function *(next) {
+ const start = new Date();
+ yield next;
+ const ms = new Date() - start;
+ console.log(`${this.method} ${this.url} - ${ms}ms`);
+}));
+```
+
+## Upgrading Middleware
+
+You will have to convert your generators to async functions with the new middleware signature:
+
+```js
+app.use(async ctx => {
+ const user = await Users.getById(this.session.user_id)
+ ctx.body = { message: 'some message' }
+})
+```
+
+Upgrading your middleware may require some work. One migration path is to update them one-by-one.
+
+1. Wrap all your current middleware in koa-convert
+2. Test
+3. npm outdated to see which koa middleware is outdated
+4. Update one outdated middleware, remove using koa-convert
+5. Test
+6. Repeat steps 3-5 until you're done
+
+
+## Updating Your Code
+
+You should start refactoring your code now to ease migrating to Koa v2:
+
+- Return promises everywhere!
+- Do not use `yield*`
+- Do not use `yield {}` or `yield []`.
+ - Convert `yield []` into `yield Promise.all([])`
+ - Convert `yield {}` into `yield Bluebird.props({})`
+
+You could also refactor your logic outside of Koa middleware functions. Create functions like 
+`function* someLogic(ctx) {}` and call it in your middleware as 
+`const result = yield someLogic(this)`.
+Not using `this` will help migrations to the new middleware signature, which does not use `this`.
+
+## Dependency Changes
+
+- [co](https://github.com/tj/co) is no longer bundled with Koa. Require or import it directly.
+- [composition](https://github.com/thenables/composition) is no longer used and deprecated
+
+## ENV specific logging behavior removed
+
+An explicit check for the `test` environment was removed from error handling. 
+
+## V1 Support
+
+The v1.x branch is still supported and may also receive feature updates. Except for this migration
+guide, Documentation will target the latest version.
+
+## Help Out
+
+If you encounter migration related issues not covered by this migration guide, please consider 
+submitting a documentation pull request.

lib/application.js

@@ -107,8 +107,7 @@ module.exports = class Application extends Emitter {
  if (isGeneratorFunction(fn)) {
  deprecate('Support for generators will be removed in v3. ' +
  'See the documentation for examples of how to convert old middleware ' +
- 'https://github.com/koajs/koa/blob/master/Readme.md' +
- '#old-signature-middleware-v1x---deprecated');
+ 'https://github.com/koajs/koa/blob/master/docs/migration.md');
  fn = convert(fn);
  }
  debug('use %s', fn._name || fn.name || '-');