From 7a0b8c31d497ccaf4e590a794276bdbbfd0299e8 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 12 Nov 2014 18:05:19 -0800
Subject: [PATCH 01/38] Add initial draft of converting your package

---
 docs/upgrading/upgrading-your-package.md | 109 +++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 docs/upgrading/upgrading-your-package.md

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
new file mode 100644
index 000000000..55e40890c
--- /dev/null
+++ b/docs/upgrading/upgrading-your-package.md
@@ -0,0 +1,109 @@
+# Upgrading your package to 1.0 APIs
+
+Atom is rapidly approaching 1.0. Much of the effort leading up to the 1.0 has been cleaning up APIs in an attempt to future proof, and make a more pleasant experience developing packages.
+
+This document will guide you through the large bits of upgrading your package to work with 1.0 APIs.
+
+## Deprecations
+
+All of the methods that have changes emit deprecation messages when called. These messages are shown in two places: your package specs, and in Deprecation Cop.
+
+### Specs
+
+Just run your specs, and all the deprecations will be displayed in yellow.
+
+TODO: image of deprecations in specs
+
+### Deprecation Cop
+
+Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette).
+
+TODO: image of deprecations in DepCop
+
+## Views
+
+### The Old
+
+Previous to 1.0, views in packages were baked into Atom core. These views were based on jQuery and `space-pen`. They look something like this:
+
+```coffee
+{$, TextEditorView, View} = require 'atom'
+
+module.exports =
+class SomeView extends View
+  @content: ->
+    @div class: 'find-and-replace', =>
+      @div class: 'block', =>
+        @subview 'myEditor', new TextEditorView(mini: true)
+  #...
+```
+
+Requiring `atom` used to provide the following view helpers:
+
+```
+$
+$$
+$$$
+View
+TextEditorView
+ScrollView
+SelectListView
+Workspace
+WorkspaceView
+```
+
+### The New
+
+Atom no longer provides these view helpers baked in. They are now available from two npm packages: `space-pen`, and `atom-space-pen-views`
+
+`space-pen` now provides
+
+```
+$
+$$
+$$$
+View
+```
+
+`atom-space-pen-views` now provides
+
+```
+TextEditorView
+ScrollView
+SelectListView
+```
+
+`Workspace` and `WorkspaceView` are _no longer provided_ in any capacity. They should be unnecessary
+
+#### jQuery
+
+If you do not need `space-pen`, you can require jQuery directly. In your `package.json` add this to the `dependencies` object:
+
+```js
+"jquery": "^2"
+```
+
+#### NPM dependencies
+
+```js
+{
+  "dependencies": {
+    "jquery": "^2" // if you want to include jquery directly
+    "space-pen": "^3"
+    "atom-space-pen-views": "^0"
+  }
+}
+```
+
+#### Converting your views
+
+Sometimes it should be as simple as converting the requires at the top of each view page. In the case of our above example, you can just convert them to the following:
+
+```coffee
+{$, View} = require 'space-pen'
+{TextEditorView} = require 'atom-space-pen-views'
+```
+
+## Specs
+
+TODO: come up with patterns for

From 0239c7d38638b32ea9e023783ae00e65597d7293 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Thu, 13 Nov 2014 18:02:26 -0800
Subject: [PATCH 02/38] Update structure of the docs a bit

---
 docs/upgrading/upgrading-your-package.md | 29 ++++++++++++------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 55e40890c..a59b322d3 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -22,9 +22,7 @@ TODO: image of deprecations in DepCop
 
 ## Views
 
-### The Old
-
-Previous to 1.0, views in packages were baked into Atom core. These views were based on jQuery and `space-pen`. They look something like this:
+Previous to 1.0, views in packages were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:
 
 ```coffee
 {$, TextEditorView, View} = require 'atom'
@@ -75,29 +73,32 @@ SelectListView
 
 `Workspace` and `WorkspaceView` are _no longer provided_ in any capacity. They should be unnecessary
 
-#### jQuery
+### Adding the module dependencies
 
-If you do not need `space-pen`, you can require jQuery directly. In your `package.json` add this to the `dependencies` object:
-
-```js
-"jquery": "^2"
-```
-
-#### NPM dependencies
+To use the new views, you need to specify a couple modules in your package dependencies in your `package.json` file:
 
 ```js
 {
   "dependencies": {
-    "jquery": "^2" // if you want to include jquery directly
     "space-pen": "^3"
     "atom-space-pen-views": "^0"
   }
 }
 ```
 
-#### Converting your views
+`space-pen` bundles jQuery. If you do not need `space-pen`, you can require jQuery directly.
 
-Sometimes it should be as simple as converting the requires at the top of each view page. In the case of our above example, you can just convert them to the following:
+```js
+{
+  "dependencies": {
+    "jquery": "^2"
+  }
+}
+```
+
+### Converting your views
+
+Sometimes it is as simple as converting the requires at the top of each view page. In the case of our above example, you can just convert them to the following:
 
 ```coffee
 {$, View} = require 'space-pen'

From ed9c62f883b5d303123ba3a2d09b733bba08df25 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Thu, 13 Nov 2014 18:02:48 -0800
Subject: [PATCH 03/38] Add a section on converting a SelectListView

---
 docs/upgrading/upgrading-your-package.md | 97 +++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index a59b322d3..ec98786f4 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -105,6 +105,101 @@ Sometimes it is as simple as converting the requires at the top of each view pag
 {TextEditorView} = require 'atom-space-pen-views'
 ```
 
+If you are using the lifecycle hooks, you will need to update code as well.
+
+### Upgrading to space-pen's TextEditorView
+
+You should not need to change anything to use the new `TextEditorView`! See the [docs][TextEditorView] for more info.
+
+### Upgrading to space-pen's ScrollView
+
+See the [docs][ScrollView] for all the options.
+
+### Upgrading to space-pen's SelectListView
+
+Your SelectListView might look something like this:
+
+```coffee
+class CommandPaletteView extends SelectListView
+  initialize: ->
+    super
+    @addClass('command-palette overlay from-top')
+    atom.workspaceView.command 'command-palette:toggle', => @toggle()
+
+  confirmed: ({name, jQuery}) ->
+    @cancel()
+    # do something with the result
+
+  toggle: ->
+    if @hasParent()
+      @cancel()
+    else
+      @attach()
+
+  attach: ->
+    @storeFocusedElement()
+
+    items = # build items
+    @setItems(items)
+
+    atom.workspaceView.append(this)
+    @focusFilterEditor()
+
+  confirmed: ({name, jQuery}) ->
+    @cancel()
+```
+
+This attaches and detaches itself from the dom when toggled, canceling magically detaches it from the DOM, and it uses the classes `overlay` and `from-top`.
+
+Using the new APIs it should look like this:
+
+```coffee
+class CommandPaletteView extends SelectListView
+  initialize: ->
+    super
+    # no more need for the `overlay` and `from-top` classes
+    @addClass('command-palette')
+    atom.workspaceView.command 'command-palette:toggle', => @toggle()
+
+  # You need to implement the `cancelled` method and hide.
+  cancelled: ->
+    @hide()
+
+  confirmed: ({name, jQuery}) ->
+    @cancel()
+    # do something with the result
+
+  toggle: ->
+    # Toggling now checks panel visibility,
+    # and hides / shows rather than attaching to / detaching from the DOM.
+    if @panel?.isVisible()
+      @cancel()
+    else
+      @show()
+
+  show: ->
+    # Now you will add your select list as a modal panel to the workspace
+    @panel ?= atom.workspace.addModalPanel(item: this)
+    @panel.show()
+
+    @storeFocusedElement()
+
+    items = # build items
+    @setItems(items)
+
+    @focusFilterEditor()
+
+  hide: ->
+    @panel?.hide()
+```
+
+See the [SelectListView docs][SelectListView] for all the options.
+
 ## Specs
 
-TODO: come up with patterns for
+TODO: come up with patterns for converting away from using `workspaceView` and `editorView`s everywhere.
+
+
+[texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
+[scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
+[selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview

From 14a20147c66d5535fcbc28e7ca0e3033600796e9 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Thu, 13 Nov 2014 18:05:01 -0800
Subject: [PATCH 04/38] Add an example

---
 docs/upgrading/upgrading-your-package.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index ec98786f4..5f7e3e128 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -193,7 +193,7 @@ class CommandPaletteView extends SelectListView
     @panel?.hide()
 ```
 
-See the [SelectListView docs][SelectListView] for all the options.
+See the [SelectListView docs][SelectListView] for all the options. And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
 
 ## Specs
 
@@ -203,3 +203,4 @@ TODO: come up with patterns for converting away from using `workspaceView` and `
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
+[selectlistview-example]:https://github.com/atom/command-palette/pull/19/files

From 612e972ac6aab97841551039ed8e398f75874f91 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Fri, 12 Dec 2014 17:36:54 -0800
Subject: [PATCH 05/38] Add tl;dr section

---
 docs/upgrading/upgrading-your-package.md | 58 +++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 5f7e3e128..e1c6002c7 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -4,9 +4,65 @@ Atom is rapidly approaching 1.0. Much of the effort leading up to the 1.0 has be
 
 This document will guide you through the large bits of upgrading your package to work with 1.0 APIs.
 
+## TL;DR
+
+We've set deprecation messages and errors in strategic places to help make sure you dont miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you need to do to enable all these errors and deprecations.
+
+### Use atom-space-pen-views
+
+Add the `atom-space-pen-views` module to your package's `package.json` file's dependencies:
+
+```js
+{
+  "dependencies": {
+    "atom-space-pen-views": "^0.21"
+  }
+}
+```
+
+Then run `apm install` in your package directory.
+
+### Require views from atom-space-pen-views
+
+Anywhere you are requiring one of the following from `atom` you need to require them from `atom-space-pen-views` instead.
+
+```js
+// require these from 'atom-space-pen-views' rather than 'atom'
+$
+$$
+$$$
+View
+TextEditorView
+ScrollView
+SelectListView
+```
+
+So this:
+
+```coffee
+# Old way
+{$, TextEditorView, View, GitRepository} = require 'atom'
+```
+
+Would be replaced with this:
+
+```coffee
+# New way
+{GitRepository} = require 'atom'
+{$, TextEditorView, View} = require 'atom-space-pen-views'
+```
+
+### Run specs and test your package
+
+You wrote specs, right!? Here's where they shine. Run them with `cmd-shift-P`, and search for `run package specs`. It will show all the deprecation messages and errors.
+
+### Examples
+
+We have upgraded all the core packages. Please see [this issue](https://github.com/atom/atom/issues/4011) for a link to all the upgrade PRs.
+
 ## Deprecations
 
-All of the methods that have changes emit deprecation messages when called. These messages are shown in two places: your package specs, and in Deprecation Cop.
+All of the methods in core that have changes will emit deprecation messages when called. These messages are shown in two places: your **package specs**, and in **Deprecation Cop**.
 
 ### Specs
 

From e8ab37c20771113cc488fe3ab5dc410403f62413 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Fri, 12 Dec 2014 17:37:26 -0800
Subject: [PATCH 06/38] Update the View Changes section

---
 docs/upgrading/upgrading-your-package.md | 31 ++++++++++++++----------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index e1c6002c7..5d44780a7 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -70,17 +70,20 @@ Just run your specs, and all the deprecations will be displayed in yellow.
 
 TODO: image of deprecations in specs
 
+TODO: Comand line spec deprecation image?
+
 ### Deprecation Cop
 
 Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette).
 
 TODO: image of deprecations in DepCop
 
-## Views
+## View Changes
 
 Previous to 1.0, views in packages were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:
 
 ```coffee
+# The old way: getting views from atom
 {$, TextEditorView, View} = require 'atom'
 
 module.exports =
@@ -92,7 +95,7 @@ class SomeView extends View
   #...
 ```
 
-Requiring `atom` used to provide the following view helpers:
+Requiring `atom` _used to_ provide the following view helpers:
 
 ```
 $
@@ -102,13 +105,11 @@ View
 TextEditorView
 ScrollView
 SelectListView
-Workspace
-WorkspaceView
 ```
 
 ### The New
 
-Atom no longer provides these view helpers baked in. They are now available from two npm packages: `space-pen`, and `atom-space-pen-views`
+Atom no longer provides these view helpers baked in. Atom core is now 'view agnostic'. The preexisting view system is available from two npm packages: `space-pen`, and `atom-space-pen-views`
 
 `space-pen` now provides
 
@@ -119,30 +120,34 @@ $$$
 View
 ```
 
-`atom-space-pen-views` now provides
+`atom-space-pen-views` now provides all of `space-pen`, plus Atom specific views:
 
-```
+```js
+// Passed through from space-pen
+$
+$$
+$$$
+View
+
+// Atom specific views
 TextEditorView
 ScrollView
 SelectListView
 ```
 
-`Workspace` and `WorkspaceView` are _no longer provided_ in any capacity. They should be unnecessary
-
 ### Adding the module dependencies
 
-To use the new views, you need to specify a couple modules in your package dependencies in your `package.json` file:
+To use the new views, you need to specify the `atom-space-pen-views` module in your package's `package.json` file's dependencies:
 
 ```js
 {
   "dependencies": {
-    "space-pen": "^3"
-    "atom-space-pen-views": "^0"
+    "atom-space-pen-views": "^0.21"
   }
 }
 ```
 
-`space-pen` bundles jQuery. If you do not need `space-pen`, you can require jQuery directly.
+`space-pen` bundles jQuery. If you do not need `space-pen` or any of the views, you can require jQuery directly.
 
 ```js
 {

From 3bb62b6651a8b91bec5a87ea04382e7f9d868fdc Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Fri, 12 Dec 2014 17:37:39 -0800
Subject: [PATCH 07/38] Update converting view section

---
 docs/upgrading/upgrading-your-package.md | 66 ++++++++++++++++++++----
 1 file changed, 57 insertions(+), 9 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 5d44780a7..155c35fd9 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -159,24 +159,71 @@ To use the new views, you need to specify the `atom-space-pen-views` module in y
 
 ### Converting your views
 
-Sometimes it is as simple as converting the requires at the top of each view page. In the case of our above example, you can just convert them to the following:
+Sometimes it is as simple as converting the requires at the top of each view page. I assume you read the 'TL;DR' section and have updated all of your requires.
+
+### Upgrading classes extending any space-pen View
+
+The `afterAttach` and `beforeRemove` hooks have been replaced with
+`attached` and `detached` and their semantics have been altered. `attached` will only be called when all parents of the View are attached to the DOM.
 
 ```coffee
-{$, View} = require 'space-pen'
-{TextEditorView} = require 'atom-space-pen-views'
+# Old way
+{View} = require 'atom'
+class MyView extends View
+  afterAttach: (onDom) ->
+    #...
+
+  beforeRemove: ->
+    #...
 ```
 
-If you are using the lifecycle hooks, you will need to update code as well.
+```coffee
+# New way
+{View} = require 'atom-space-pen-views'
+class MyView extends View
+  attached: ->
+    # Always called with the equivalent of @afterAttach(true)!
+    #...
 
-### Upgrading to space-pen's TextEditorView
+  removed: ->
+    #...
+```
+
+### Upgrading to the new TextEditorView
 
 You should not need to change anything to use the new `TextEditorView`! See the [docs][TextEditorView] for more info.
 
-### Upgrading to space-pen's ScrollView
+### Upgrading to classes extending ScrollView
 
-See the [docs][ScrollView] for all the options.
+The `ScrollView` has very minor changes.
 
-### Upgrading to space-pen's SelectListView
+You can no longer use `@off` to remove default behavior for `core:move-up`, `core:move-down`, etc.
+
+```coffee
+# Old way to turn off default behavior
+class ResultsView extends ScrollView
+  initialize: (@model) ->
+    super
+    # turn off default scrolling behavior from ScrollView
+    @off 'core:move-up'
+    @off 'core:move-down'
+    @off 'core:move-left'
+    @off 'core:move-right'
+```
+
+```coffee
+# New way to turn off default behavior
+class ResultsView extends ScrollView
+  initialize: (@model) ->
+    disposable = super()
+    # turn off default scrolling behavior from ScrollView
+    disposable.dispose()
+```
+
+* Check out [an example](https://github.com/atom/find-and-replace/pull/311/files#diff-9) from find-and-replace.
+* See the [docs][ScrollView] for all the options.
+
+### Upgrading to classes extending SelectListView
 
 Your SelectListView might look something like this:
 
@@ -254,7 +301,8 @@ class CommandPaletteView extends SelectListView
     @panel?.hide()
 ```
 
-See the [SelectListView docs][SelectListView] for all the options. And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
+* And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
+* See the [SelectListView docs][SelectListView] for all options.
 
 ## Specs
 

From 6520587ba82163c15cf06784452ce474de81ad4d Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Mon, 5 Jan 2015 15:46:00 -0800
Subject: [PATCH 08/38] Add section about updating specs

---
 docs/upgrading/upgrading-your-package.md | 95 +++++++++++++++++++++++-
 1 file changed, 93 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 155c35fd9..1442a061f 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -304,9 +304,100 @@ class CommandPaletteView extends SelectListView
 * And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
 * See the [SelectListView docs][SelectListView] for all options.
 
-## Specs
+## Updating Specs
 
-TODO: come up with patterns for converting away from using `workspaceView` and `editorView`s everywhere.
+`WorkspaceView` and `EditorView` have been deprecated. These two objects are used heavily throughout specs, mostly to dispatch events and commands. This section will explain how to remove them while still retaining the ability to dispatch events and commands.
+
+### Removing WorkspaceView references
+
+`WorkspaceView` has been deprecated. Everything you could do on the view, you can now do on the `Workspace` model.
+
+Requiring `WorkspaceView` from `atom` and accessing any methods on it will throw a deprecation warning. Many specs lean heavily on `WorkspaceView` to trigger commands and fetch `EditorView` objects.
+
+Your specs might contain something like this:
+
+```coffee
+# Old!
+{WorkspaceView} = require 'atom'
+describe 'FindView', ->
+  beforeEach ->
+    atom.workspaceView = new WorkspaceView()
+```
+
+Instead, we will use the `atom.views.getView()` method. This will return a plain `HTMLElement`, not a `WorkspaceView` or jQuery object.
+
+```coffee
+# New!
+describe 'FindView', ->
+  workspaceElement = null
+  beforeEach ->
+    workspaceElement = atom.views.getView(atom.workspace)
+```
+
+### Attaching the workspace to the DOM
+
+The workspace needs to be attached to the DOM in some cases. For example, view hooks only work (`attached()` on `View`, `attachedCallback()` on custom elements) when there is a descendant attached to the DOM.
+
+You might see this in your specs:
+
+```coffee
+# Old!
+atom.workspaceView.attachToDom()
+```
+
+Change it to:
+
+```coffee
+# New!
+jasmine.attachToDOM(workspaceElement)
+```
+
+### Removing EditorView references
+
+Like `WorkspaceView`, `EditorView` has been deprecated. Everything you needed to do on the view you are now able to do on the `Editor` model.
+
+In many cases, you will not even need to get the editor's view anymore. Any of those instances should be updated to use the `Editor` instance. You should really only need the editor's view when you plan on triggering a command on the view in a spec.
+
+Your specs might contain something like this:
+
+```coffee
+# Old!
+describe 'Something', ->
+  [editorView] = []
+  beforeEach ->
+    editorView = atom.workspaceView.getActiveView()
+```
+
+We're going to use `atom.views.getView()` again to get the editor element. As in the case of the `workspaceElement`, `getView` will return a plain `HTMLElement` rather than an `EditorView` or jQuery object.
+
+```coffee
+# New!
+describe 'Something', ->
+  [editor, editorElement] = []
+  beforeEach ->
+    editor = atom.workspace.getActiveTextEditor()
+    editorElement = atom.views.getView(editor)
+```
+
+### Dispatching commands
+
+Since the `editorView` objects are no longer `jQuery` objects, they no longer support `trigger()`. Additionally, Atom has a new command dispatcher, `atom.commands`, that we use rather than commandeering jQuery's `trigger` method.
+
+From this:
+
+```coffee
+# Old!
+workspaceView.trigger 'a-package:toggle'
+editorView.trigger 'find-and-replace:show'
+```
+
+To this:
+
+```coffee
+# New!
+atom.commands.dispatch workspaceElement, 'a-package:toggle'
+atom.commands.dispatch editorElement, 'find-and-replace:show'
+```
 
 
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview

From e3eadc310de43a0debed49e0a9bcc4ad67cb27d9 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Mon, 5 Jan 2015 17:20:11 -0800
Subject: [PATCH 09/38] Add guide section about events and the emitter.

---
 docs/upgrading/upgrading-your-package.md | 129 +++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 1442a061f..7d07f3216 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -399,8 +399,137 @@ atom.commands.dispatch workspaceElement, 'a-package:toggle'
 atom.commands.dispatch editorElement, 'find-and-replace:show'
 ```
 
+## Eventing and Disposables
+
+A couple large things changed with respect to events:
+
+1. All model events are now methods that return a [`Disposable`][disposable] object
+1. The `subscribe()` method is no longer available on `space-pen` `View` objects
+1. An Emitter is now provided from `require 'atom'`
+
+### Consuming Events
+
+All events from the Atom API are now methods that return a [`Disposable`][disposable] object, on which you can call `dispose()` to unsubscribe.
+
+```coffee
+# Old!
+editor.on 'changed', ->
+```
+
+```coffee
+# New!
+disposable = editor.onDidChange ->
+
+# You can unsubscribe at some point in the future via `dispose()`
+disposable.dispose()
+```
+
+Deprecation warnings will guide you toward the correct methods.
+
+#### Using a CompositeDisposable
+
+You can group multiple disposables into a single disposable with a `CompositeDisposable`.
+
+```coffee
+{CompositeDisposable} = require 'atom'
+
+class Something
+  constructor: ->
+    @disposables.add editor.onDidChange ->
+    @disposables.add editor.onDidChangePath ->
+
+  destroy: ->
+    @disposables.dispose()
+```
+
+### Removing View::subscribe calls
+
+There were a couple permutations of `subscribe()`. In these examples, a `CompositeDisposable` is used as it will commonly be useful where conversion is necessary.
+
+#### subscribe(unsubscribable)
+
+This one is very straight forward.
+
+```coffee
+# Old!
+@subscribe editor.on 'changed', ->
+```
+
+```coffee
+# New!
+disposables = new CompositeDisposable
+disposables.add editor.onDidChange ->
+```
+
+#### subscribe(modelObject, event, method)
+
+When the modelObject is an Atom model object, the change is very simple. Just use the correct event method, and add it to your CompositeDisposable.
+
+```coffee
+# Old!
+@subscribe editor, 'changed', ->
+```
+
+```coffee
+# New!
+disposables = new CompositeDisposable
+disposables.add editor.onDidChange ->
+```
+
+#### subscribe(jQueryObject, selector(optional), event, method)
+
+Things are a little more complicated when subscribing to a DOM or jQuery element. Atom no longer provides helpers for subscribing to elements. You can use jQuery or the native DOM APIs, whichever you prefer.
+
+```coffee
+# Old!
+@subscribe $(window), 'focus', ->
+```
+
+```coffee
+# New!
+{Disposable, CompositeDisposable} = require 'atom'
+disposables = new CompositeDisposable
+
+# New with jQuery
+focusCallback = ->
+$(window).on 'focus', focusCallback
+disposables.add new Disposable ->
+  $(window).off 'focus', focusCallback
+
+# New with native APIs
+focusCallback = ->
+window.addEventListener 'focus', focusCallback
+disposables.add new Disposable ->
+  window.removeEventListener 'focus', focusCallback
+```
+
+### Providing Events: Using the Emitter
+
+You no longer need to require emissary to get an emitter. We now provide an `Emitter` class from `require 'atom'`. We have a specific pattern for use of the `Emitter`. Rather than mixing it in, we instantiate a member variable, and create explicit subscription methods. For more information see the [`Emitter` docs][emitter].
+
+```coffee
+# New!
+{Emitter} = require 'atom'
+
+class Something
+  constructor: ->
+    @emitter = new Emitter
+
+  destroy: ->
+    @emitter.dispose()
+
+  onDidChange: (callback) ->
+    @emitter.on 'did-change', callback
+
+  methodThatFiresAChange: ->
+    @emitter.emit 'did-change'
+```
+
+## Subscribing To Commands
 
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
 [selectlistview-example]:https://github.com/atom/command-palette/pull/19/files
+[emitter]:https://atom.io/docs/api/latest/Emitter
+[disposable]:https://atom.io/docs/api/latest/Disposable

From 0ea2a9dc9ce3158a503430618fc21399e3512423 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Mon, 5 Jan 2015 17:34:31 -0800
Subject: [PATCH 10/38] Add guide section on subscribing to commands

---
 docs/upgrading/upgrading-your-package.md | 25 +++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 7d07f3216..6539507a4 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -442,7 +442,7 @@ class Something
     @disposables.dispose()
 ```
 
-### Removing View::subscribe calls
+### Removing View::subscribe and Subscriber::subscribe calls
 
 There were a couple permutations of `subscribe()`. In these examples, a `CompositeDisposable` is used as it will commonly be useful where conversion is necessary.
 
@@ -527,9 +527,32 @@ class Something
 
 ## Subscribing To Commands
 
+`$.fn.command` and `View::subscribeToCommand` are no longer available. Now we use `atom.commands.add`, and collect the results in a `CompositeDisposable`. See [the docs][commands-add] for more info.
+
+```coffee
+# Old!
+atom.workspaceView.command 'core:close core:cancel', ->
+
+# When inside a View class, you might see this
+@subscribeToCommand 'core:close core:cancel', ->
+```
+
+```coffee
+# New!
+@disposables.add atom.commands.add 'atom-workspace',
+  'core:close': ->
+  'core:cancel': ->
+
+# When in a View class, you should have a `@element` object available. `@element` is a raw HTML element
+@disposables.add atom.commands.add @element,
+  'core:close': ->
+  'core:cancel': ->
+```
+
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
 [selectlistview-example]:https://github.com/atom/command-palette/pull/19/files
 [emitter]:https://atom.io/docs/api/latest/Emitter
 [disposable]:https://atom.io/docs/api/latest/Disposable
+[commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add

From 13fa424ed5e39757657a4767d51c75e0bf1cae85 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Mon, 5 Jan 2015 17:41:12 -0800
Subject: [PATCH 11/38] Add upgrading selectors section to package upgrade
 guide

---
 docs/upgrading/upgrading-your-package.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 6539507a4..7a3e04e5e 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -549,6 +549,10 @@ atom.workspaceView.command 'core:close core:cancel', ->
   'core:cancel': ->
 ```
 
+## Upgrading your stylesheet's selectors
+
+See [Upgrading Your Package Selectors guide][upgrading-selectors] for more information.
+
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
@@ -556,3 +560,4 @@ atom.workspaceView.command 'core:close core:cancel', ->
 [emitter]:https://atom.io/docs/api/latest/Emitter
 [disposable]:https://atom.io/docs/api/latest/Disposable
 [commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add
+[upgrading-selectors]:upgrading-your-ui-theme

From 77aa539e703121029def1b77696fd4558cded129 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Mon, 5 Jan 2015 17:46:31 -0800
Subject: [PATCH 12/38] Update a bit of the guide

---
 docs/upgrading/upgrading-your-package.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 7a3e04e5e..990f62419 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -10,7 +10,7 @@ We've set deprecation messages and errors in strategic places to help make sure
 
 ### Use atom-space-pen-views
 
-Add the `atom-space-pen-views` module to your package's `package.json` file's dependencies:
+If you use any class from `require 'atom'` with a `$` or `View` in the name, add the `atom-space-pen-views` module to your package's `package.json` file's dependencies:
 
 ```js
 {
@@ -62,7 +62,7 @@ We have upgraded all the core packages. Please see [this issue](https://github.c
 
 ## Deprecations
 
-All of the methods in core that have changes will emit deprecation messages when called. These messages are shown in two places: your **package specs**, and in **Deprecation Cop**.
+All of the methods in Atom core that have changes will emit deprecation messages when called. These messages are shown in two places: your **package specs**, and in **Deprecation Cop**.
 
 ### Specs
 
@@ -78,9 +78,9 @@ Run an atom window in dev mode (`atom -d`) with your package loaded, and open De
 
 TODO: image of deprecations in DepCop
 
-## View Changes
+## Upgrading your Views
 
-Previous to 1.0, views in packages were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:
+Previous to 1.0, views were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:
 
 ```coffee
 # The old way: getting views from atom
@@ -228,6 +228,7 @@ class ResultsView extends ScrollView
 Your SelectListView might look something like this:
 
 ```coffee
+# Old!
 class CommandPaletteView extends SelectListView
   initialize: ->
     super
@@ -262,6 +263,7 @@ This attaches and detaches itself from the dom when toggled, canceling magically
 Using the new APIs it should look like this:
 
 ```coffee
+# New!
 class CommandPaletteView extends SelectListView
   initialize: ->
     super

From 87c217c3f62a8847461c33ce4681b2507625a2fc Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 13:42:19 -0800
Subject: [PATCH 13/38] =?UTF-8?q?Fix=20don=E2=80=99t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/upgrading/upgrading-your-package.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 990f62419..8bd08e4c4 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -6,7 +6,7 @@ This document will guide you through the large bits of upgrading your package to
 
 ## TL;DR
 
-We've set deprecation messages and errors in strategic places to help make sure you dont miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you need to do to enable all these errors and deprecations.
+We've set deprecation messages and errors in strategic places to help make sure you don't miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you need to do to enable all these errors and deprecations.
 
 ### Use atom-space-pen-views
 

From e0f6642a9b2090b7188a36121a562e074bb7060f Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 13:42:32 -0800
Subject: [PATCH 14/38] with -> by

---
 docs/upgrading/upgrading-your-package.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 8bd08e4c4..7805791a7 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -44,7 +44,7 @@ So this:
 {$, TextEditorView, View, GitRepository} = require 'atom'
 ```
 
-Would be replaced with this:
+Would be replaced by this:
 
 ```coffee
 # New way

From dfbb50385d18c7575f704dfe0aa07a5ab3e0932d Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 13:49:11 -0800
Subject: [PATCH 15/38] Comment :lipstick:

---
 docs/upgrading/upgrading-your-package.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 7805791a7..85d7d6086 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -26,8 +26,8 @@ Then run `apm install` in your package directory.
 
 Anywhere you are requiring one of the following from `atom` you need to require them from `atom-space-pen-views` instead.
 
-```js
-// require these from 'atom-space-pen-views' rather than 'atom'
+```coffee
+# require these from 'atom-space-pen-views' rather than 'atom'
 $
 $$
 $$$

From 2cf5df858fa90ba2fcd45c2906b3bbdec705e40e Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 13:49:39 -0800
Subject: [PATCH 16/38] Be more clear about the export from
 atom-space-pen-views

---
 docs/upgrading/upgrading-your-package.md | 24 ++----------------------
 1 file changed, 2 insertions(+), 22 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 85d7d6086..eb91c23aa 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -95,32 +95,12 @@ class SomeView extends View
   #...
 ```
 
-Requiring `atom` _used to_ provide the following view helpers:
-
-```
-$
-$$
-$$$
-View
-TextEditorView
-ScrollView
-SelectListView
-```
-
 ### The New
 
-Atom no longer provides these view helpers baked in. Atom core is now 'view agnostic'. The preexisting view system is available from two npm packages: `space-pen`, and `atom-space-pen-views`
+`require 'atom'` no longer provides view helpers or jQuery. Atom core is now 'view agnostic'. The preexisting view system is available from a new npm package: `atom-space-pen-views`.
 
-`space-pen` now provides
+`atom-space-pen-views` now provides jQuery, `space-pen` views, plus Atom specific views:
 
-```
-$
-$$
-$$$
-View
-```
-
-`atom-space-pen-views` now provides all of `space-pen`, plus Atom specific views:
 
 ```js
 // Passed through from space-pen

From 2743c0ab6f5df5af13857740471039c05a3b7691 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 14:58:38 -0800
Subject: [PATCH 17/38] Upgrade versions of atom-space-pen-views

---
 docs/upgrading/upgrading-your-package.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index eb91c23aa..37f157068 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -15,7 +15,7 @@ If you use any class from `require 'atom'` with a `$` or `View` in the name, add
 ```js
 {
   "dependencies": {
-    "atom-space-pen-views": "^0.21"
+    "atom-space-pen-views": "^2.0.2"
   }
 }
 ```
@@ -122,7 +122,7 @@ To use the new views, you need to specify the `atom-space-pen-views` module in y
 ```js
 {
   "dependencies": {
-    "atom-space-pen-views": "^0.21"
+    "atom-space-pen-views": "^2.0.2"
   }
 }
 ```

From f10453ed049ed54ff320ad24eff411064667c5fb Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 14:59:03 -0800
Subject: [PATCH 18/38] Reword parts of the guide for clarity

---
 docs/upgrading/upgrading-your-package.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 37f157068..efe11e380 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -99,17 +99,15 @@ class SomeView extends View
 
 `require 'atom'` no longer provides view helpers or jQuery. Atom core is now 'view agnostic'. The preexisting view system is available from a new npm package: `atom-space-pen-views`.
 
-`atom-space-pen-views` now provides jQuery, `space-pen` views, plus Atom specific views:
+`atom-space-pen-views` now provides jQuery, `space-pen` views, and Atom specific views:
 
 
-```js
-// Passed through from space-pen
+```coffee
+# These are now provided by atom-space-pen-views
 $
 $$
 $$$
 View
-
-// Atom specific views
 TextEditorView
 ScrollView
 SelectListView
@@ -144,7 +142,7 @@ Sometimes it is as simple as converting the requires at the top of each view pag
 ### Upgrading classes extending any space-pen View
 
 The `afterAttach` and `beforeRemove` hooks have been replaced with
-`attached` and `detached` and their semantics have been altered. `attached` will only be called when all parents of the View are attached to the DOM.
+`attached` and `detached`. The `attached` method semantics have changed: it will only be called when all parents of the View are attached to the DOM. The `detached` semantics have not changed.
 
 ```coffee
 # Old way
@@ -165,7 +163,7 @@ class MyView extends View
     # Always called with the equivalent of @afterAttach(true)!
     #...
 
-  removed: ->
+  detached: ->
     #...
 ```
 

From d523f9e1ecc1163fd2ba90e73a29769d0a51db5e Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 15:08:04 -0800
Subject: [PATCH 19/38] Add images of deprecations

---
 docs/upgrading/upgrading-your-package.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index efe11e380..2484deb09 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -68,15 +68,15 @@ All of the methods in Atom core that have changes will emit deprecation messages
 
 Just run your specs, and all the deprecations will be displayed in yellow.
 
-TODO: image of deprecations in specs
+![spec-deps](https://cloud.githubusercontent.com/assets/69169/5637943/b85114ba-95b5-11e4-8681-b81ea8f556d7.png)
+
 
-TODO: Comand line spec deprecation image?
 
 ### Deprecation Cop
 
 Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette).
 
-TODO: image of deprecations in DepCop
+![dep-cop](https://cloud.githubusercontent.com/assets/69169/5637914/6e702fa2-95b5-11e4-92cc-a236ddacee21.png)
 
 ## Upgrading your Views
 

From 979fad966dbca4b319a2c66ddfbf1710d63c79f0 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 15:11:15 -0800
Subject: [PATCH 20/38] :lipstick:

---
 docs/upgrading/upgrading-your-package.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 2484deb09..a559bb10e 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -70,8 +70,6 @@ Just run your specs, and all the deprecations will be displayed in yellow.
 
 ![spec-deps](https://cloud.githubusercontent.com/assets/69169/5637943/b85114ba-95b5-11e4-8681-b81ea8f556d7.png)
 
-
-
 ### Deprecation Cop
 
 Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette).

From b8fa3a2127cd902a3032d4e8594f6979d941a638 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 16:17:40 -0800
Subject: [PATCH 21/38] Cleanup based on @kevinsawicki feedback

---
 docs/upgrading/upgrading-your-package.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index a559bb10e..a4a184b65 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -179,7 +179,7 @@ You can no longer use `@off` to remove default behavior for `core:move-up`, `cor
 # Old way to turn off default behavior
 class ResultsView extends ScrollView
   initialize: (@model) ->
-    super
+    super()
     # turn off default scrolling behavior from ScrollView
     @off 'core:move-up'
     @off 'core:move-down'
@@ -207,7 +207,7 @@ Your SelectListView might look something like this:
 # Old!
 class CommandPaletteView extends SelectListView
   initialize: ->
-    super
+    super()
     @addClass('command-palette overlay from-top')
     atom.workspaceView.command 'command-palette:toggle', => @toggle()
 
@@ -242,10 +242,10 @@ Using the new APIs it should look like this:
 # New!
 class CommandPaletteView extends SelectListView
   initialize: ->
-    super
+    super()
     # no more need for the `overlay` and `from-top` classes
     @addClass('command-palette')
-    atom.workspaceView.command 'command-palette:toggle', => @toggle()
+    atom.commands.add 'atom-workspace', 'command-palette:toggle', => @toggle()
 
   # You need to implement the `cancelled` method and hide.
   cancelled: ->
@@ -270,7 +270,7 @@ class CommandPaletteView extends SelectListView
 
     @storeFocusedElement()
 
-    items = # build items
+    items = [] # TODO: build items
     @setItems(items)
 
     @focusFilterEditor()
@@ -351,10 +351,10 @@ We're going to use `atom.views.getView()` again to get the editor element. As in
 ```coffee
 # New!
 describe 'Something', ->
-  [editor, editorElement] = []
+  [editor, editorView] = []
   beforeEach ->
     editor = atom.workspace.getActiveTextEditor()
-    editorElement = atom.views.getView(editor)
+    editorView = atom.views.getView(editor)
 ```
 
 ### Dispatching commands
@@ -374,7 +374,7 @@ To this:
 ```coffee
 # New!
 atom.commands.dispatch workspaceElement, 'a-package:toggle'
-atom.commands.dispatch editorElement, 'find-and-replace:show'
+atom.commands.dispatch editorView, 'find-and-replace:show'
 ```
 
 ## Eventing and Disposables

From 75857bec01d8a8ae56cf0e85f738ea02d42c639e Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 16:19:21 -0800
Subject: [PATCH 22/38] Update items to equal an array

---
 docs/upgrading/upgrading-your-package.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index a4a184b65..35101f8b9 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -224,7 +224,7 @@ class CommandPaletteView extends SelectListView
   attach: ->
     @storeFocusedElement()
 
-    items = # build items
+    items = [] # TODO: build items
     @setItems(items)
 
     atom.workspaceView.append(this)

From a17b504bdbd7b3f1e30877995e361df73b76d1e1 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 16:58:39 -0800
Subject: [PATCH 23/38] Add missing line to upgrade guide

---
 docs/upgrading/upgrading-your-package.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 35101f8b9..52016d0cd 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -413,6 +413,7 @@ You can group multiple disposables into a single disposable with a `CompositeDis
 
 class Something
   constructor: ->
+    editor = atom.workspace.getActiveTextEditor()
     @disposables.add editor.onDidChange ->
     @disposables.add editor.onDidChangePath ->
 

From 909ec375b1716e9909ceb91a53631157a0e98058 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 16:58:51 -0800
Subject: [PATCH 24/38] Remove unnecessary `to`s

---
 docs/upgrading/upgrading-your-package.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 52016d0cd..95d441ae5 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -169,7 +169,7 @@ class MyView extends View
 
 You should not need to change anything to use the new `TextEditorView`! See the [docs][TextEditorView] for more info.
 
-### Upgrading to classes extending ScrollView
+### Upgrading classes extending ScrollView
 
 The `ScrollView` has very minor changes.
 
@@ -199,7 +199,7 @@ class ResultsView extends ScrollView
 * Check out [an example](https://github.com/atom/find-and-replace/pull/311/files#diff-9) from find-and-replace.
 * See the [docs][ScrollView] for all the options.
 
-### Upgrading to classes extending SelectListView
+### Upgrading classes extending SelectListView
 
 Your SelectListView might look something like this:
 

From 40b465b0b61412f9d41f5719a0a7418d6fa2754c Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:08:07 -0800
Subject: [PATCH 25/38] Update deprecation cop summary

---
 docs/upgrading/upgrading-your-package.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 95d441ae5..7b73e5a52 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -72,10 +72,12 @@ Just run your specs, and all the deprecations will be displayed in yellow.
 
 ### Deprecation Cop
 
-Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette).
+Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette). Deprecated methods will be appear in Deprecation Cop only after they have been called.
 
 ![dep-cop](https://cloud.githubusercontent.com/assets/69169/5637914/6e702fa2-95b5-11e4-92cc-a236ddacee21.png)
 
+When deprecation cop is open, and deprecated methods are called, a `Refresh` button will appear in the top right of the Deprecation Cop interface. So exercise your package, then come back to Deprecation Cop and click the `Refresh` button.
+
 ## Upgrading your Views
 
 Previous to 1.0, views were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:

From 1eba8cff39eb345b4d9e2e6623aa0d2235faceb9 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:14:20 -0800
Subject: [PATCH 26/38] Update text about attached and detached semantics

---
 docs/upgrading/upgrading-your-package.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 7b73e5a52..19aaf823a 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -142,7 +142,11 @@ Sometimes it is as simple as converting the requires at the top of each view pag
 ### Upgrading classes extending any space-pen View
 
 The `afterAttach` and `beforeRemove` hooks have been replaced with
-`attached` and `detached`. The `attached` method semantics have changed: it will only be called when all parents of the View are attached to the DOM. The `detached` semantics have not changed.
+`attached` and `detached` and the semantics have changed.
+
+`afterAttach` was called whenever the node was attached to another DOM node, even if that node itself wasn't present in the document. `afterAttach` also was called with a boolean indicating whether or not the element and its parents were on the DOM. Now the `attached` hook is only called when the node and all of its parents are actually on the DOM, and is not called with a boolean.
+
+`beforeRemove` was only called when `$.fn.remove` was called, which was typically used when the node was completely removed from the DOM. The `detached` hook is called whenever the DOM node is _detached_, which could happen if the node is being detached for reattachment later. In short, if `beforeRemove` is called the node is never coming back. With `detached` it might be attached again later.
 
 ```coffee
 # Old way

From e62485195a7b01eff54252d7358403abecc0c1fc Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:18:56 -0800
Subject: [PATCH 27/38] Update the docs on TextEditorView

---
 docs/upgrading/upgrading-your-package.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 19aaf823a..c814cf0bb 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -173,7 +173,7 @@ class MyView extends View
 
 ### Upgrading to the new TextEditorView
 
-You should not need to change anything to use the new `TextEditorView`! See the [docs][TextEditorView] for more info.
+All of the atom-specific methods available on the `TextEditorView` have been moved to the `TextEditor`, available via `TextEditorView::getModel`. See the [`TextEditorView` docs][TextEditorView] and [`TextEditor` docs][TextEditor] for more info.
 
 ### Upgrading classes extending ScrollView
 
@@ -543,6 +543,7 @@ See [Upgrading Your Package Selectors guide][upgrading-selectors] for more infor
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
 [selectlistview-example]:https://github.com/atom/command-palette/pull/19/files
 [emitter]:https://atom.io/docs/api/latest/Emitter
+[texteditor]:https://atom.io/docs/api/latest/TextEditor
 [disposable]:https://atom.io/docs/api/latest/Disposable
 [commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add
 [upgrading-selectors]:upgrading-your-ui-theme

From 67c193c5cef2530a21ee252e3d0701a8df1afe37 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:22:00 -0800
Subject: [PATCH 28/38] Update the guide's selectListView upgrade text

---
 docs/upgrading/upgrading-your-package.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index c814cf0bb..4a60da72f 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -242,7 +242,7 @@ class CommandPaletteView extends SelectListView
 
 This attaches and detaches itself from the dom when toggled, canceling magically detaches it from the DOM, and it uses the classes `overlay` and `from-top`.
 
-Using the new APIs it should look like this:
+The new SelectListView no longer automatically detaches itself from the DOM when cancelled. It's up to you to implement whatever cancel beahavior you want. Using the new APIs to mimic the sematics of the old class, it should look like this:
 
 ```coffee
 # New!

From f2d495eab23fa57062a8dbc9aaf1dba3901c5192 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:42:20 -0800
Subject: [PATCH 29/38] Update the guide to have a section on using the model
 layer.

---
 docs/upgrading/upgrading-your-package.md | 42 +++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 4a60da72f..bf0cc548e 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -288,9 +288,49 @@ class CommandPaletteView extends SelectListView
 * And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
 * See the [SelectListView docs][SelectListView] for all options.
 
+## Using the model layer rather than the view layer
+
+The API no longer exposes any view objects or view classes. `atom.workspaceView`, and all the view classes: `WorkspaceView`, `EditorView`, `PaneView`, etc. have been globally deprecated.
+
+Nearly all of the atom-specific actions performed by the old view objects can now be managed via the model layer. For example, here's adding a panel to the interface using the `atom.workspace` model instead of the `workspaceView`:
+
+```coffee
+# Old!
+div = document.createElement('div')
+atom.workspaceView.appendToTop(div)
+```
+
+```coffee
+# New!
+div = document.createElement('div')
+atom.workspace.addTopPanel(item: div)
+```
+
+For actions that still require the view, such as dispatching commands or munging css classes, you'll access the view via the `atom.views.getView()` method. This will return a subclass of `HTMLElement` rather than a jQuery object or an instance of a deprecated view class (e.g. `WorkspaceView`).
+
+```coffee
+# Old!
+workspaceView = atom.workspaceView
+editorView = workspaceView.getActiveEditorView()
+paneView = editorView.getPaneView()
+```
+
+```coffee
+# New!
+# Generally, just use the models
+workspace = atom.workspace
+editor = workspace.getActiveTextEditor()
+pane = editor.getPane()
+
+# If you need views, get them with `getView`
+workspaceElement = atom.views.getView(atom.workspace)
+editorElement = atom.views.getView(editor)
+paneElement = atom.views.getView(pane)
+```
+
 ## Updating Specs
 
-`WorkspaceView` and `EditorView` have been deprecated. These two objects are used heavily throughout specs, mostly to dispatch events and commands. This section will explain how to remove them while still retaining the ability to dispatch events and commands.
+`atom.workspaceView`, the `WorkspaceView` class and the `EditorView` class have been deprecated. These two objects are used heavily throughout specs, mostly to dispatch events and commands. This section will explain how to remove them while still retaining the ability to dispatch events and commands.
 
 ### Removing WorkspaceView references
 

From 2c093213159457166ea7b25208d3ca3c941d155a Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:47:23 -0800
Subject: [PATCH 30/38] :lipstick:

---
 docs/upgrading/upgrading-your-package.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index bf0cc548e..32a49f69c 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -378,9 +378,9 @@ jasmine.attachToDOM(workspaceElement)
 
 ### Removing EditorView references
 
-Like `WorkspaceView`, `EditorView` has been deprecated. Everything you needed to do on the view you are now able to do on the `Editor` model.
+Like `WorkspaceView`, `EditorView` has been deprecated. Everything you needed to do on the view you are now able to do on the `TextEditor` model.
 
-In many cases, you will not even need to get the editor's view anymore. Any of those instances should be updated to use the `Editor` instance. You should really only need the editor's view when you plan on triggering a command on the view in a spec.
+In many cases, you will not even need to get the editor's view anymore. Any of those instances should be updated to use the `TextEditor` instance instead. You should really only need the editor's view when you plan on triggering a command on the view in a spec.
 
 Your specs might contain something like this:
 
@@ -392,7 +392,7 @@ describe 'Something', ->
     editorView = atom.workspaceView.getActiveView()
 ```
 
-We're going to use `atom.views.getView()` again to get the editor element. As in the case of the `workspaceElement`, `getView` will return a plain `HTMLElement` rather than an `EditorView` or jQuery object.
+We're going to use `atom.views.getView()` again to get the editor element. As in the case of the `workspaceElement`, `getView` will return a subclass of `HTMLElement` rather than an `EditorView` or jQuery object.
 
 ```coffee
 # New!

From 08456105950c7378d87240ac6847509c9e4cfeb8 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:47:33 -0800
Subject: [PATCH 31/38] editorView -> editorElement again

---
 docs/upgrading/upgrading-your-package.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 32a49f69c..d9949a779 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -397,15 +397,15 @@ We're going to use `atom.views.getView()` again to get the editor element. As in
 ```coffee
 # New!
 describe 'Something', ->
-  [editor, editorView] = []
+  [editor, editorElement] = []
   beforeEach ->
     editor = atom.workspace.getActiveTextEditor()
-    editorView = atom.views.getView(editor)
+    editorElement = atom.views.getView(editor)
 ```
 
 ### Dispatching commands
 
-Since the `editorView` objects are no longer `jQuery` objects, they no longer support `trigger()`. Additionally, Atom has a new command dispatcher, `atom.commands`, that we use rather than commandeering jQuery's `trigger` method.
+Since the `editorElement` objects are no longer `jQuery` objects, they no longer support `trigger()`. Additionally, Atom has a new command dispatcher, `atom.commands`, that we use rather than commandeering jQuery's `trigger` method.
 
 From this:
 
@@ -420,14 +420,14 @@ To this:
 ```coffee
 # New!
 atom.commands.dispatch workspaceElement, 'a-package:toggle'
-atom.commands.dispatch editorView, 'find-and-replace:show'
+atom.commands.dispatch editorElement, 'find-and-replace:show'
 ```
 
 ## Eventing and Disposables
 
 A couple large things changed with respect to events:
 
-1. All model events are now methods that return a [`Disposable`][disposable] object
+1. All model events are now exposed as event subscription methods that return [`Disposable`][disposable] objects
 1. The `subscribe()` method is no longer available on `space-pen` `View` objects
 1. An Emitter is now provided from `require 'atom'`
 

From 1bba80c2b22b8ce18a0963673cf87774186cb554 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:54:52 -0800
Subject: [PATCH 32/38] Add an example of an arg with the emitter

---
 docs/upgrading/upgrading-your-package.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index d9949a779..7f95fd5bb 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -547,7 +547,12 @@ class Something
     @emitter.on 'did-change', callback
 
   methodThatFiresAChange: ->
-    @emitter.emit 'did-change'
+    @emitter.emit 'did-change', {data: 2}
+
+something = new Something
+something.onDidChange (eventObject) ->
+  console.log eventObject.data # => 2
+something.methodThatFiresAChange()
 ```
 
 ## Subscribing To Commands
@@ -568,7 +573,9 @@ atom.workspaceView.command 'core:close core:cancel', ->
   'core:close': ->
   'core:cancel': ->
 
-# When in a View class, you should have a `@element` object available. `@element` is a raw HTML element
+# You can register commands directly on individual DOM elements in addition to
+# using selectors. When in a View class, you should have a `@element` object
+# available. `@element` is a plain HTMLElement object
 @disposables.add atom.commands.add @element,
   'core:close': ->
   'core:cancel': ->

From 7f3e0287ebec8732ed81eac37e561c175278264a Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Tue, 6 Jan 2015 18:57:56 -0800
Subject: [PATCH 33/38] Add bit about removal of subscribe() in upgrading your
 View section

---
 docs/upgrading/upgrading-your-package.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 7f95fd5bb..88035da71 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -141,6 +141,8 @@ Sometimes it is as simple as converting the requires at the top of each view pag
 
 ### Upgrading classes extending any space-pen View
 
+#### `afterAttach` and `beforeRemove` updated
+
 The `afterAttach` and `beforeRemove` hooks have been replaced with
 `attached` and `detached` and the semantics have changed.
 
@@ -171,6 +173,10 @@ class MyView extends View
     #...
 ```
 
+#### `subscribe` and `subscribeToCommand` methods removed
+
+Additionally, the `subscribe` and `subscribeToCommand` methods have been removed. See the Eventing and Disposables section for more info.
+
 ### Upgrading to the new TextEditorView
 
 All of the atom-specific methods available on the `TextEditorView` have been moved to the `TextEditor`, available via `TextEditorView::getModel`. See the [`TextEditorView` docs][TextEditorView] and [`TextEditor` docs][TextEditor] for more info.

From e2609ddd061a1494aeae75a453d67d8732d42c20 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 7 Jan 2015 11:40:02 -0800
Subject: [PATCH 34/38] New version of atom-space-pen-views

---
 docs/upgrading/upgrading-your-package.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 88035da71..aff78b57a 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -15,7 +15,7 @@ If you use any class from `require 'atom'` with a `$` or `View` in the name, add
 ```js
 {
   "dependencies": {
-    "atom-space-pen-views": "^2.0.2"
+    "atom-space-pen-views": "^2.0.3"
   }
 }
 ```
@@ -120,7 +120,7 @@ To use the new views, you need to specify the `atom-space-pen-views` module in y
 ```js
 {
   "dependencies": {
-    "atom-space-pen-views": "^2.0.2"
+    "atom-space-pen-views": "^2.0.3"
   }
 }
 ```

From bb6446f7d05dc98da6543078b10ac5deccb4ea27 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 7 Jan 2015 11:40:17 -0800
Subject: [PATCH 35/38] Update wording in tldr of guide

---
 docs/upgrading/upgrading-your-package.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index aff78b57a..a012ad570 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -6,7 +6,7 @@ This document will guide you through the large bits of upgrading your package to
 
 ## TL;DR
 
-We've set deprecation messages and errors in strategic places to help make sure you don't miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you need to do to enable all these errors and deprecations.
+We've set deprecation messages and errors in strategic places to help make sure you don't miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you can do to get the full effect of all the errors and deprecations.
 
 ### Use atom-space-pen-views
 

From c172882c159db4b7c150cf4c593eceeb20fb02ba Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 7 Jan 2015 11:56:10 -0800
Subject: [PATCH 36/38] Package upgrade guide :lipstick:

---
 docs/upgrading/upgrading-your-package.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index a012ad570..e0271adc2 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -146,9 +146,9 @@ Sometimes it is as simple as converting the requires at the top of each view pag
 The `afterAttach` and `beforeRemove` hooks have been replaced with
 `attached` and `detached` and the semantics have changed.
 
-`afterAttach` was called whenever the node was attached to another DOM node, even if that node itself wasn't present in the document. `afterAttach` also was called with a boolean indicating whether or not the element and its parents were on the DOM. Now the `attached` hook is only called when the node and all of its parents are actually on the DOM, and is not called with a boolean.
+`afterAttach` was called whenever the node was attached to another DOM node, even if that parent node wasn't present in the DOM. `afterAttach` also was called with a boolean indicating whether or not the element and its parents were on the DOM. Now the `attached` hook is _only_ called when the node and all of its parents are actually on the DOM, and is not called with a boolean.
 
-`beforeRemove` was only called when `$.fn.remove` was called, which was typically used when the node was completely removed from the DOM. The `detached` hook is called whenever the DOM node is _detached_, which could happen if the node is being detached for reattachment later. In short, if `beforeRemove` is called the node is never coming back. With `detached` it might be attached again later.
+`beforeRemove` was only called when `$.fn.remove` was called, which was typically used when the node was completely removed from the DOM. The new `detached` hook is called whenever the DOM node is _detached_, which could happen if the node is being detached for reattachment later. In short, if `beforeRemove` is called the node is never coming back. With `detached` it might be attached again later.
 
 ```coffee
 # Old way
@@ -175,7 +175,7 @@ class MyView extends View
 
 #### `subscribe` and `subscribeToCommand` methods removed
 
-Additionally, the `subscribe` and `subscribeToCommand` methods have been removed. See the Eventing and Disposables section for more info.
+The `subscribe` and `subscribeToCommand` methods have been removed. See the Eventing and Disposables section for more info.
 
 ### Upgrading to the new TextEditorView
 
@@ -296,7 +296,7 @@ class CommandPaletteView extends SelectListView
 
 ## Using the model layer rather than the view layer
 
-The API no longer exposes any view objects or view classes. `atom.workspaceView`, and all the view classes: `WorkspaceView`, `EditorView`, `PaneView`, etc. have been globally deprecated.
+The API no longer exposes any specialized view objects or view classes. `atom.workspaceView`, and all the view classes: `WorkspaceView`, `EditorView`, `PaneView`, etc. have been globally deprecated.
 
 Nearly all of the atom-specific actions performed by the old view objects can now be managed via the model layer. For example, here's adding a panel to the interface using the `atom.workspace` model instead of the `workspaceView`:
 
@@ -466,6 +466,7 @@ You can group multiple disposables into a single disposable with a `CompositeDis
 class Something
   constructor: ->
     editor = atom.workspace.getActiveTextEditor()
+    @disposables = new CompositeDisposable
     @disposables.add editor.onDidChange ->
     @disposables.add editor.onDidChangePath ->
 
@@ -536,7 +537,7 @@ disposables.add new Disposable ->
 
 ### Providing Events: Using the Emitter
 
-You no longer need to require emissary to get an emitter. We now provide an `Emitter` class from `require 'atom'`. We have a specific pattern for use of the `Emitter`. Rather than mixing it in, we instantiate a member variable, and create explicit subscription methods. For more information see the [`Emitter` docs][emitter].
+You no longer need to require `emissary` to get an emitter. We now provide an `Emitter` class from `require 'atom'`. We have a specific pattern for use of the `Emitter`. Rather than mixing it in, we instantiate a member variable, and create explicit subscription methods. For more information see the [`Emitter` docs][emitter].
 
 ```coffee
 # New!
@@ -555,6 +556,7 @@ class Something
   methodThatFiresAChange: ->
     @emitter.emit 'did-change', {data: 2}
 
+# Using the evented class
 something = new Something
 something.onDidChange (eventObject) ->
   console.log eventObject.data # => 2
@@ -589,7 +591,7 @@ atom.workspaceView.command 'core:close core:cancel', ->
 
 ## Upgrading your stylesheet's selectors
 
-See [Upgrading Your Package Selectors guide][upgrading-selectors] for more information.
+Many selectors have changed, and we have introduced the [Shadow DOM][shadowdom] to the editor. See [Upgrading Your Package Selectors guide][upgrading-selectors] for more information in upgrading your package stylesheets.
 
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
@@ -600,3 +602,4 @@ See [Upgrading Your Package Selectors guide][upgrading-selectors] for more infor
 [disposable]:https://atom.io/docs/api/latest/Disposable
 [commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add
 [upgrading-selectors]:upgrading-your-ui-theme
+[shadowdom]:http://blog.atom.io/2014/11/18/avoiding-style-pollution-with-the-shadow-dom.html

From 9fcac1ab1cb48c50fdd21914678c632a568b2340 Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 7 Jan 2015 12:04:41 -0800
Subject: [PATCH 37/38] Add a bit about contributing to the guide

---
 docs/upgrading/upgrading-your-package.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index e0271adc2..3a6c2e976 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -593,6 +593,13 @@ atom.workspaceView.command 'core:close core:cancel', ->
 
 Many selectors have changed, and we have introduced the [Shadow DOM][shadowdom] to the editor. See [Upgrading Your Package Selectors guide][upgrading-selectors] for more information in upgrading your package stylesheets.
 
+## Help us improve this guide!
+
+Did you hit something painful that wasn't in here? Want to reword some bit of it? Find something incorrect? Please edit [this file][guide], and send a pull request. Contributions are greatly appreciated.
+
+
+
+
 [texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
 [scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
 [selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
@@ -603,3 +610,4 @@ Many selectors have changed, and we have introduced the [Shadow DOM][shadowdom]
 [commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add
 [upgrading-selectors]:upgrading-your-ui-theme
 [shadowdom]:http://blog.atom.io/2014/11/18/avoiding-style-pollution-with-the-shadow-dom.html
+[guide]:https://github.com/atom/atom/blob/master/docs/upgrading/upgrading-your-package.md

From ab9cc75f8b09b5b167dbc02c63d8223e3d0f257b Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Wed, 7 Jan 2015 13:55:09 -0800
Subject: [PATCH 38/38] Add bit about the engines field

---
 docs/upgrading/upgrading-your-package.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 3a6c2e976..8ad1ae2fb 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -56,6 +56,18 @@ Would be replaced by this:
 
 You wrote specs, right!? Here's where they shine. Run them with `cmd-shift-P`, and search for `run package specs`. It will show all the deprecation messages and errors.
 
+### Update the engines field in package.json
+
+When you are deprecation free and all done converting, upgrade the `engines` field in your package.json:
+
+```json
+{
+  "engines": {
+    "atom": ">=0.x.0, <2.0.0"
+  }
+}
+```
+
 ### Examples
 
 We have upgraded all the core packages. Please see [this issue](https://github.com/atom/atom/issues/4011) for a link to all the upgrade PRs.