deprecate {{with}}, introduce {{if-let}}

text/0000-template.md

@@ -0,0 +1,90 @@
+- Start Date: 2019-02-13
+- Relevant Teams: Ember.js, Learning
+- RFC PR: https://github.com/emberjs/rfcs/pull/445
+- Tracking: (leave this empty)
+
+# Deprecate `{{with}}`, introduce `{{if-let}}`
+
+## Summary
+
+The `{{with}}` helper has always had slightly confusing conditional semantics, this was one of the motivators for [introducing](https://github.com/emberjs/rfcs/blob/master/text/0286-block-let-template-helper.md) the easier to understand `{{let}}` helper. Now that `{{let}}` exists, the remaining use case for using `{{with}}` is for its unique conditional semantics. The name `{{with}}` doesn't accurately represent the helpers behavior, we should rename it to `{{if-let}}`.
+
+## Motivation
+
+The difference between `{{let}}` and `{{with}}` is with how they handle conditional arguments. The `{{let}}` helper's block content is always rendered, regardless of its parameters. In contrast, `{{with}}` only renders its main block when the first position parameter is truthy. For example:
+
+```hbs
+{{#with "Alex" as |value|}}
+  {{value}} is truthy
+{{else}}
+  The first positional param was falsy
+{{/with}}
+```
+
+Will render "[Alex] is truthy".
+
+```hbs
+{{#with false as |value|}}
+  {{value}} is truthy
+{{else}}
+  The first positional param was falsy
+{{/with}}
+```
+
+Will render "The first positional param was falsy".
+
+As the naming of `{{with}}` doesn't give any indication of its behavior, we should deprecate it and introducing the better named `{{if-let}}` helper. Doing do will make Ember easier to learn and use.
+
+Here's how the `{{with}}` examples above would look like when using `{{if-let}}`:
+
+```hbs
+{{#if-let "Alex" as |value|}}
+  {{value}} is truthy
+{{else}}
+  The first positional param was falsy
+{{/if-let}}
+```
+
+Will render "[Alex] is truthy".
+
+```hbs
+{{#if-let false as |value|}}
+  {{value}} is truthy
+{{else}}
+  The first positional param was falsy
+{{/if-let}}
+```
+
+## Detailed design
+
+We'll create a new `{{if-let}}` helper which will have the same behavior to the current [`{{with}}` helper](https://github.com/glimmerjs/glimmer-vm/blob/a15a7c86ae50a882f3f395a394cdaff6211ade30/packages/%40glimmer/opcode-compiler/lib/syntax/builtins.ts#L81-L106).
+
+We'll create an AST transform in [`packages/ember-template-compiler`](https://github.com/emberjs/ember.js/tree/master/packages/ember-template-compiler) which will emit a deprecation warning for all uses of `{{with}}`. The deprecation warning will be something like:
+
+```
+Using `{{with}}` is deprecated, please use the `{{let}}` or `{{if-let}}` helpers instead.
+```
+
+This new deprecation warning should link to some docs which clearly describe when you should use `{{let}}` and when you should use `{{let-if}}`.
+
+## How we teach this
+
+We'll add `{{if-let}}` documentation to the [`Ember.Templates.helpers` API docs](https://www.emberjs.com/api/ember/3.7/classes/Ember.Templates.helpers). The new documentation should make the unique use cases of `{{if-let}}` clear. 
+
+We'll mentiton the new `{{if-let}}` helper in an Ember point release blog post.
+
+The deprecation message will link to good docs which describe why `{{with}}` was deprecated and give clear guidlines on how to migrate to using either `{{let}}` or `{{if-let}}`.
+
+## Drawbacks
+
+This adds a litte API and documentation churn.
+
+## Alternatives
+
+We could leave `{{with}}` as is. I don't believe that this is a good option as the name `{{with}}` is far from ideal.
+
+We could deprecate `{{with}}` and introduce `{{if-let}}` in an addon instead of Ember core.
+
+## Unresolved questions
+
+None