Merge pull request #2700 from josemarluedke/deprecate-render-helper

Add deprecation guide for {{render helper

source/deprecations/v2.x.html.md

@@ -753,3 +753,107 @@ component.appendTo('.my-component-wrapper');
 ```
 
 Note that both APIs are private, so no public API is been deprecated here.
+
+
+#### `{{render` helper
+
+##### until: 3.0.0
+##### id: ember-template-compiler.deprecate-render
+
+Using the `{{render` helper is deprecated in favor of using components.
+Please refactor uses of this helper to components:
+
+For example, if you had:
+
+```hbs
+{{render 'my-sidebar'}}
+```
+
+```hbs
+{{! app/templates/my-sidebar.hbs }}
+<p>template stuff here</p>
+```
+
+```js
+// app/controllers/my-sidebar.js
+export default Ember.Controller.extend({
+});
+```
+
+You would refactor to a component like so:
+
+```hbs
+{{my-sidebar}}
+```
+
+```hbs
+{{! app/templates/components/my-sidebar.hbs }}
+<p>template stuff here</p>
+```
+
+```js
+// app/components/my-sidebar.js
+export default Ember.Component.extend({
+});
+```
+
+Note that the render helper has several unique behaviors that may require further refactoring work during migration to a component.
+
+- When using the render helper with no model argument, the controller instance is a singleton. For example the same controller instance is shared between `{{render 'post'}}`, any other helper usage of `{{render 'post'}}`, a route template named post, and dependency injections using `Ember.inject.service('post')`.
+- When sendAction is called in a rendered controller, or when `{{action` is used in a render helper template, the bubbling target for those actions is the router and current active route. With components, those same actions would target only the component instance without bubbling.
+
+
+#### Rendering into a {{render}} helper that resolves to an {{outlet}}.
+
+##### until: 3.0.0
+##### id: ember-routing.top-level-render-helper
+
+Before named outlets were introduced to Ember the render helper was used to declare slots for `this.render` in routes. This usage is not common in modern, idiomatic applications and is deprecated. In general, the pattern of named outlets or named render helpers is discouraged. Instead use of [ember-elsewhere](https://github.com/ef4/ember-elsewhere) or another DOM-redirection library should better serve these use cases.
+
+For example this code uses the render helper as a target for a special sidebar present on the index route. The special sidebar is in a template named `index-sidebar`:
+
+```hbs
+{{! app/templates/application.hbs }}
+<div class="sidebar">{{render 'sidebar'}}</div>
+<div class="main">{{outlet}}</div>
+```
+
+```hbs
+{{! app/templates/index.hbs }}
+Index Content
+```
+
+```js
+// app/routes/index.js
+App.IndexRoute = Ember.Route.extend({
+  renderTemplate() {
+    this._super(...arguments);
+    this.render('index-sidebar', { into: 'sidebar' });
+  },
+  actions: {
+    willTransition() {
+      this.disconnectOutlet({
+        parentView: 'application',
+        outlet: 'sidebar'
+      });
+    }
+  }
+});
+```
+
+It should be refactored to use [ember-elsewhere](https://github.com/ef4/ember-elsewhere). The sidebar content must be implemented as a component, in this case named `index-sidebar`. The logic previously used in the route file can be removed. The refactored example:
+
+```hbs
+{{! app/templates/application.hbs }}
+<div class="sidebar">{{from-elsewhere name='sidebar'}}</div>
+<div class="main">{{outlet}}</div>
+```
+
+```hbs
+{{! app/templates/index.hbs }}
+{{to-elsewhere named='sidebar' send=(component 'index-sidebar')}}
+Index Content
+```
+
+For more informations of how to use `ember-elsewhere`, please visit the official
+documentation [here](https://github.com/ef4/ember-elsewhere#ember-elsewhere).