Update migration guide to be accurate.

0.11-migration-guide.md

@@ -20,15 +20,44 @@ To do this, just remove your sails.io.js client and install the new one.  We've
 sails generate sails.io.js --force
 ```
 
-####  Update configuration in `config/sockets.js`
 
-Many of the configuration options in Socket.io v1 have changed, so you'll want to update your `config/sockets.js` file accordingly.
+####  `onConnect` lifecycle callback
+
+> **tldr;**
+>
+> Remove your `onConnect` function from `config/sockets.js`.
+
+The `onConnect` lifecycle callback has been deprecated.  Instead, if you need to do something when a new socket is connected, send a request from the newly-connected client to do so.  The purpose of `onConnect` was always for optimizing performance (eliminating the need to do this initial extra round-trip with the server), yet its use can lead to confusion and race conditions. If you desperately need to eliminate the server roundtrip, you can bind a handler directly on `sails.io.on('connect', function (newlyConnectedSocket){})` in your bootstrap function (`config/bootstrap.js`). However, note that this is discouraged.  Unless you're facing _true_ production performance issues, you should use the strategy mentioned above for your "on connection" logic (i.e. send an initial request from the client after the socket connects).  Socket requests are lightweight, so this doesn't add any tangible overhead to your application, and it will help make your code more predictable.
+
+
+
+####  `onDisconnect` lifecycle callback
+
+The `onDisconnect` lifecycle callback has been deprecated in favor of `afterDisconnect`.
+
+If you were using `onDisconnect` previously, you might have had to change the `session`, then call `session.save()` manually.  In v0.11, this works in almost exactly the same way, except that `afterDisconnect` receives an additional 3rd argument: a callback function.  This way, you can just call the provided callback when your `afterDisconnect` logic has finished, so that Sails can persist any changes you've made to the session automatically.  Finally, as you might expect, you won't need to call `session.save()` manually anymore- it is now taken care of for you (just like `req.session` in a normal route, action, or policy.)
 
-Here's a short summary of the steps necessary to upgrade the average project:
 
-+ if you were using a custom `authorization` function to restrict socket connections, you'll now want to use `allowRequest`.  `authorization` was deprecated by Socket.io v1, but `allowRequest` from Engine.io works just the same way.
+> **tldr;**
+> Rename your `onDisconnect` function in `config/sockets.js` with the following:
+>
+> ```
+> afterDisconnect: function (session, socket, cb) {
+>   // Be sure to call the callback
+>   return cb();
+> }
+> ```
+
+
+
+
+####  Other configuration in `config/sockets.js`
+
+Many of the configuration options in Socket.io v1 have changed, so you'll want to update your `config/sockets.js` file accordingly.
+
++ if you were using a custom `authorization` function to restrict socket connections, you'll now want to use `beforeConnect`.  `authorization` was deprecated by Socket.io v1, but `beforeConnect` (which maps to the `allowRequest` option from Engine.io) works just the same way.
 + if you were using other low-level socket configuration that was passed directly to socket.io v1, be sure and check out the [reference page on sailsjs.org](http://sailsjs.org/#/documentation/reference/sails.config/sails.config.sockets.html) where all of the new configuration options are covered in detail.
-+ The `session` argument provided to the `sails.config.sockets.onConnect` and `sails.config.sockets.onDisconnect` functions is now read-only.  In other words, if you were using these functions previously, you might change `session`, then call `session.save()`. In v0.11, this will no longer work-- it has been disabled, since it can lead to race conditions in your code.  Instead, if you need to change the session when a new socket is connected, send a request from the newly-connected client to do so.  Note that support for accessing the session may be added again in the future, but not as part of `onConnect` and `onDisconnect`.  Instead, it would likely be included as part of the `beforeConnect` and `afterDisconnect` lifecycle callbcks on our roadmap (these new functions would add a callback argument, which Sails could use as an indicator of when it should automatically persist the session).
+
 
 #### The "firehose"
 
@@ -39,7 +68,7 @@ The "firehose" feature for testing with sockets has been deprecated.  If you don
   + sails.sockets.spit()
   + sails.sockets.squirt()
 
-> If you want the "firehose" back, let [Mike know on twitter](http://twitter.com/mikermcneil) (it can be brought back as a separate hook). But... yeah.
+> If you want the "firehose" back, let [Mike know on twitter](http://twitter.com/mikermcneil) (it can be brought back as a separate hook).