From cfef799d6d0a5086716cf17ffc47778e7400027c Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Sat, 2 Mar 2019 02:03:21 -0500
Subject: [PATCH 1/7] First draft

---
 ...update-on-module-unification-and-octane.md | 380 ++++++++++++++++++
 1 file changed, 380 insertions(+)
 create mode 100644 source/blog/2019-03-02-update-on-module-unification-and-octane.md

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
new file mode 100644
index 0000000000..acc724f0ef
--- /dev/null
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -0,0 +1,380 @@
+---
+title: 'Update on Module Unification & Octane'
+author: Tom Dale
+tags: Recent Posts, 2019, Ember Octane
+responsive: true
+---
+
+Ember's conventions for project layout and file naming are central to the
+developer experience. It's crucial that we get both the technical and
+ergonomic details right. I wanted to provide an update about Module
+Unification and our plans for the file structure in Ember Octane.
+
+In short, we intend to make templates play nicely with JavaScript, so you can
+use the `import` feature you already know and love. By having components and
+helpers be modules you can import, we can simplify Module Unification so it's
+easier to learn and use.
+
+Here's an example of what I think template imports could look like:
+
+```js
+// src/ui/components/blog-post.gbs
+
+import Component from '@glimmer/component';
+import UserProfile from './user-profile';
+import UserIcon from './icons/user';
+
+export class BlogPost extends Component {
+  blog = { title: 'Coming soon in Octane', authorId: '1234' }
+
+  <template>
+    <h1>{{this.blog.title}}</h1>
+    <UserIcon />
+    <UserProfile @userId={{this.blog.authorId}} />
+  </template>
+}
+```
+
+Here, we've imported two components—`UserProfile` and `UserIcon`—like we
+would any other JavaScript module. We've also defined the component's
+template in JavaScript, placing it in in a template tag within the class
+body.
+
+For templates that aren't associated with a component (such as route
+templates), we could allow template tags to be exported from JavaScript as
+well:
+
+```js
+// src/ui/routes/application.gbs
+
+import NavBar from '../components/NavBar';
+
+export default <template>
+  <NavBar @darkMode={{true}} />
+  <main>
+    {{outlet}}
+  </main>
+</template>;
+```
+
+While the framework core team has reached consensus that template imports are
+the path forward, please note that the syntax shown in the examples above is
+hypothetical. While I'm personally a fan of the `<template>` tag syntax shown
+here, others are not, and details like this are still being hammered out in
+the RFC process and are highly likely to change.
+
+Speaking for the framework core team, we are trying to get better at updating
+the community when plans have changed but the _new_ plan isn't locked
+in yet.
+
+So, consider this one of those situations. We know Module Unification, [as
+defined in the original MU RFC][mu], needs some changes before it's ready for
+prime time. We are still figuring out exactly what those changes are, and
+exactly the shape of the template imports design. Keep an eye on the [RFCs
+repo][rfcs], where we'll be sharing these proposals as soon as they're ready.
+
+[mu]: https://emberjs.github.io/rfcs/0143-module-unification.html
+[rfcs]: https://github.com/emberjs/rfcs
+
+The MU RFC was merged in late 2016. It's fair to ask why implementing MU has
+taken this long, and why it took this long to realize we wanted to make
+changes. In the spirit of transparency and overcommunication, I wanted to
+share a little bit of the history and evolution of MU from my perspective.
+
+## A Little History
+
+Today, Ember apps use the "classic" file layout by default. While this layout
+has served us well, it also has several shortcomings.
+
+Because files are grouped by type, a component's template resides in one
+directory (`app/templates/components`) while its JavaScript class resides in
+another (`app/components`). Jumping between these two directories as they
+grow can be frustrating, especially given how frequently Ember developers
+need to switch back and forth between component class and template.
+
+Early on, Ember CLI implemented an experimental "pods" layout that grouped
+files by name rather than by kind. So, for example, a component's JavaScript
+and template file would be grouped together in `app/component-name/`, as
+`component.js` and `template.hbs` respectively.
+
+User feedback was that pods felt more productive than the classic layout.
+However, pods had several problems that needed to be addressed before it could
+be enabled by default.
+
+The effort to address the design flaws of pods led to the [Module Unification
+RFC][mu], a ground-up rethink of how the file system should work in Ember
+apps. Importantly, this design grappled with overhauling Ember's resolver and
+dependency injection systems, which was as much or more important than
+deciding the particular file system layout.
+
+The MU RFC was merged at the end of 2016, but new Ember apps are still
+generated with the classic layout. So, why is that? Why can't we flip the
+switch on enabling Module Unification-style layout by default today?
+
+Remember that MU described not just a new file system but a significant
+overhaul of Ember's resolver. Implementing MU was a **huge** initiative that,
+while often hidden, touched nearly every part of the framework. Despite this
+large scope, and thanks to the incredible amount of time and energy our
+community devoted to the work, MU implementation has made great progress, and
+nearly everything needed to make Module Unification work has landed in Ember.
+
+_Nearly_ everything. There's one last major piece needed to ship, and while
+we were working on implementing MU, shifts in the JavaScript ecosystem took
+place that sent us back to the drawing board.
+
+### Namespaces and Scoped Packages
+
+One of the problems with the classic layout is that everything goes into one
+big global pool of names. So, for example, if your app has a component called
+`small-button` and you install an addon that also has a component called
+`small-button`, you have no way to tell Ember which one you mean when you
+type `{{small-button}}` in a template.
+
+One of the key benefits of the MU design is that names are no longer global,
+but namespaced to the package where they come from. So, for example, if an
+npm package called `ember-ui-library` contains a component called
+`small-button`, I would refer to it in my template as
+`{{ember-ui-library::small-button}}`.
+
+This worked pretty well, with the downside that it could get quite verbose.
+This was especially true when components were invoked with a block:
+
+```hbs
+{{#ember-ui-library::small-button}}
+  ...
+{{/ember-ui-library::small-button}}
+```
+
+Around the same time we were designing MU, [npm announced support for scoped
+package names][scoped-packages]. Prior to this change, npm package names were
+limited to alphanumeric characters and dashes. With this change, however,
+packages could now start with an `@` and be prefixed with a user or
+organization, like `@glimmer/component`.
+
+[scoped-packages]: https://blog.npmjs.org/post/116936804365/solving-npms-hard-problem-naming-packages
+
+While namespaced component invocations pushed the limits of verbosity,
+combining them with scoped packages blew past that limit. We simply could not
+bring ourselves to accept a syntax that commonly produced monstrosities like
+this:
+
+```hbs
+{{#@my-company/ember-ui-library::small-button}}
+  ...
+{{/@my-company/ember-ui-library::small-button}}
+```
+
+While Ember had been using it for years, around this time JavaScript module
+syntax (`import Post from './post'`) started gaining significant traction in
+the wider ecosystem. After scoped npm packages scuttled our original plan for
+namespaced components, we went back to the drawing board, and something
+similar to JavaScript's `import` seemed like a promising solution.
+
+However, we immediately hit some challenges while exploring this idea.
+
+First, how much do we want to be like JavaScript? Should we create a
+Handlebars-flavored version of JavaScript imports? Something about this just
+felt _wrong_:
+
+```hbs
+{{import small-component from "@my-company/ember-ui-library"}}
+```
+
+It reads like JavaScript, at the expense of being incoherent when read as
+Handlebars, whose syntax is a functional programming language in the spirit
+of Lisp. We seriously considered it, but couldn't get past additional
+problems like how to accommodate named exports (`import { thing }`) and
+wildcard imports (`import *`).
+
+Next, we thought about literally embedding JavaScript in templates, but again
+there were syntactic incompatibilities between Handlebars and JavaScript.
+Given the requirement that component names contain a dash (`-`) character,
+but JavaScript identifiers aren't allowed to contain dashes, what exactly do
+you type? `import small-component from '@my-company/ember-ui-library'` isn't
+valid JavaScript.
+
+We still felt stuck.
+
+### Real-World Feedback
+
+In the meantime, enough of Module Unification was shipping behind feature
+flags (and in Glimmer.js) that we were able to get feedback from early
+adopters. While overall people really liked the new file system and really
+appreciated not dealing with frustrating name collisions, something felt
+_off_.
+
+One common theme in the feedback was that MU felt too rigid and frequently
+got in the way of simple tasks. To understand why, it's important to
+understand that MU is about more than a file system. MU is really a system
+for _controlling scope_.
+
+For example, a feature of MU is the ability to have private components that
+don't leak into the rest of the app. If we have a component called
+`list-paginator` and it has a child component called `paginator-control`, MU
+allows us to organize them like this:
+
+```
+src
+├── ui
+│   ├── components
+│   │   └── list-paginator
+│   │       ├── paginator-control
+│   │       │   ├── component.js
+│   │       │   └── template.hbs
+│   │       ├── component.js
+│   │       └── template.js
+```
+
+In this example, the `list-paginator` template can invoke
+`{{paginator-control}}` to render its child component. However, if you try to
+invoke `{{paginator-control}}` from any template outside the `list-paginator`
+directory, you'll get an error. In other words, `paginator-control` is
+_local_ to `list-paginator`.
+
+MU, then, is about scope, and controlling who has access to what. Where a
+module lives in the MU file system determines what it can see to and who
+else can see it.
+
+This is a clever idea that eliminates a lot of boilerplate. If you have to
+organize your files anyway, and if you want to group related things together
+anyway, it makes sense to try to create a single system that solves
+organization and scoping at the same time.
+
+In practice, though, we ran into a few challenges:
+
+1. This idea is not common in the JavaScript ecosystem, so the file system
+   controlling scope isn't intuitive for new learners. They also have to
+   memorize these naming rules, which are implicit and get quite complex.
+2. Similarly, ecosystem tools don't understand MU. We have to build custom
+   integrations to get things like "Go to Definition" to work in IDEs or code
+   splitting to work in webpack, that other libraries get for free.
+3. JavaScript files in Ember use native module syntax anyway, which doesn't
+   go through the MU system, adding to the confusion. Having one system in
+   a component's JavaScript and another in its template is not ideal.
+4. When names are so meaningful, it can be frustrating to figure out how to
+   tell MU ignore something that something _isn't_ meaningful. Tasks that
+   are trivial in other programming environments, such as grouping related
+   components together, can easily turn into a battle where your build starts
+   erroring because you can't figure out the right incantation of the MU
+   rules.
+
+### A Personal Anecdote
+
+Personally, this last one was what really caused me to step back and
+re-evaluate our plan for MU. It happened during a project at work where we
+were using both Glimmer.js (with Module Unification) and Preact.
+
+As the number of components grew, a co-worker created a directory called
+`icons` in the Preact app to hold all of the components for rendering
+different SVG icons. I'm sure it didn't take more than a few minutes to
+create the directory, drag the appropriate component files in, and update the
+paths everywhere those components were imported. (In fact, VS Code probably
+updated the import paths automatically.)
+
+When we tried to do the same thing in the Glimmer app, it was a much
+different experience that turned into an hours-long slog. And despite all the
+great things it _does_ do, MU doesn't really have a way to do this kind of
+lightweight grouping.
+
+We could have extracted the SVG icon components into a separate package. We
+could have tried to create a higher-order component that wrapped all of the
+child icon components. We could have found a workaround. But it seemed
+ridiculous to burn so much time looking for a "workaround" to perform a task
+that felt like it should have been (and was, in Preact) trivial.
+
+I knew, intellectually, the benefits of MU. I knew how carefully it was
+designed to enforce structure and consistency as your application grew and
+had different engineers of different experience levels working on it. (Indeed,
+by the end of the project, I found the Glimmer app much easier to navigate,
+while the Preact app had several inconsistently-followed conventions.)
+
+But I never forgot how viscerally bad it felt to have my co-workers fight so
+hard to do something that felt like it should be so easy.
+
+### The Path Forward
+
+So this was the status quo last year. We were all incredibly frustrated that
+we couldn't make progress on the scoped package problem, but I was even more
+overwhelmed trying to figure out what, if anything, to do about the negative
+experiences my co-workers had had when using MU.
+
+Revisiting a design you've been working on for so long is painful, especially
+in cases like this where the majority of the work is already complete. We
+felt like we just had to solve the scoped package problem and we'd finally be
+done.
+
+Programming language and API design is hard. Really hard. Sometimes I read
+old RFCs and marvel at how obvious the design seems now, after the weeks,
+months, or years we spent teasing it out from the millions of possibilities
+in front of us.
+
+When you're trying to balance so many competing constraints, sometimes a
+small change is all it takes to get you out of a design conundrum you've
+struggled with for months. In this case, that change was angle bracket
+component invocation.
+
+As I mentioned above, it seemed obvious we couldn't use JavaScript for
+template imports because components had to have a dash in their name. If we
+wanted to import identifiers with a dash in the name, we'd have to invent our
+own syntax.
+
+Angle bracket components, on the other hand, start with a capital letter to
+differentiate themselves from normal HTML tags, so they use PascalCase—and no
+dash. As the Ember community started using angle bracket syntax, early
+feedback was very positive. All of a sudden, JavaScript import syntax was
+back on the table.
+
+With the renewed excitement about template imports, it was a good time to
+bring up the ergonomic concerns about MU.
+
+Without template imports, we had to rely on MU to resolve component names,
+meaning the files in the `src/ui/components` directory had to follow strict
+rules. But _with_ template imports, users can just tell us which module on
+disk they want. We can skip resolving components through MU altogether, and
+let Ember users organize their component files however they want.
+
+As frustrating as it was at the time, the inability to make progress on MU
+may have been a blessing in disguise. It gave us time to land angle bracket
+components, which allowed template imports to seem feasible again, which
+allowed us to both solve the scoped package problem while loosening the
+strictest MU rules.
+
+I think the deadend we found ourselves in was a sign from the universe that
+we needed to wait for the better design that was just around the corner. Time
+will tell, but I think template imports are a much, much better design. And
+this process also pushed us to explore single-file components, which I think
+will be a surprisingly big productivity improvement for Ember developers.
+
+I want to be clear: the is all just one person's recollection of events. The
+reality of technical design is messy and feels a lot more like going around
+in circles than the nice, clean, linear sequence I've presented here.
+
+### What's Next
+
+I recently posted the [SFC & Template Import Primitives
+RFC](https://github.com/emberjs/rfcs/pull/454), which is the first of several
+RFCs describing changes to MU or new features that complement MU. You should
+see more RFCs related to this topic in the coming weeks.
+
+I will also mention that, as a project, I think we've dramatically improved
+how we design, implement, validate, and iterate on features since we
+originally started the Module Unification RFC. The MU RFC is the last of the
+proposals from the "mega-RFC" era, where we had a tendency to do a ton of
+upfront design and implementation before we had any feedback from real users.
+
+Nowadays, I think we're a lot better about making sure RFCs are relatively
+small and focused on doing one thing and doing it well. We also tend to
+prioritize exposing hooks or other primitives that let us test out new ideas
+in addons. This allows us to improve designs based on real world feedback,
+without the strict stability requirements that come with landing something in
+the framework proper.
+
+This has worked well for things like `ember-decorators` and
+`@glimmer/component`, where real world feedback and the ability to make
+breaking changes based on that feedback was critical. I'm hopeful that a
+similar strategy for single-file components will be just as successful.
+
+I'm so excited about Ember, our technical vision, and the newfound energy in
+our community. In 2019, a thriving Ember is more important for the web than
+ever. Thank you for being a part of our community, and I hope to see you at
+EmberConf in a few weeks. It's gonna be a good one.
\ No newline at end of file

From f86af9ddad8cb76e888e1290f480f07e7360d310 Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Sat, 2 Mar 2019 02:19:11 -0500
Subject: [PATCH 2/7] wat

---
 ...9-03-02-update-on-module-unification-and-octane.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index acc724f0ef..253bcaa2df 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -251,12 +251,11 @@ In practice, though, we ran into a few challenges:
 3. JavaScript files in Ember use native module syntax anyway, which doesn't
    go through the MU system, adding to the confusion. Having one system in
    a component's JavaScript and another in its template is not ideal.
-4. When names are so meaningful, it can be frustrating to figure out how to
-   tell MU ignore something that something _isn't_ meaningful. Tasks that
-   are trivial in other programming environments, such as grouping related
-   components together, can easily turn into a battle where your build starts
-   erroring because you can't figure out the right incantation of the MU
-   rules.
+4. When file names are so meaningful, it can be frustrating to figure out how
+   to tell MU ignore a file that _isn't_ meaningful. Tasks that are trivial
+   in other programming environments, such as grouping related components
+   together, can easily turn into a battle where your build starts erroring
+   because you can't figure out the right incantation of the MU rules.
 
 ### A Personal Anecdote
 

From 33f860d8869c547bd3f0613076f96d61c3047d1f Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Sun, 3 Mar 2019 21:32:11 -0500
Subject: [PATCH 3/7] Second draft, based on feedback from mixonic and others

---
 ...update-on-module-unification-and-octane.md | 222 +++++++++++-------
 1 file changed, 135 insertions(+), 87 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index 253bcaa2df..9d3d0299e4 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -5,6 +5,8 @@ tags: Recent Posts, 2019, Ember Octane
 responsive: true
 ---
 
+<!-- alex disable fight laid burn -->
+
 Ember's conventions for project layout and file naming are central to the
 developer experience. It's crucial that we get both the technical and
 ergonomic details right. I wanted to provide an update about Module
@@ -57,29 +59,38 @@ export default <template>
 </template>;
 ```
 
-While the framework core team has reached consensus that template imports are
+While the Ember.js core team has reached consensus that template imports are
 the path forward, please note that the syntax shown in the examples above is
 hypothetical. While I'm personally a fan of the `<template>` tag syntax shown
 here, others are not, and details like this are still being hammered out in
 the RFC process and are highly likely to change.
 
-Speaking for the framework core team, we are trying to get better at updating
-the community when plans have changed but the _new_ plan isn't locked
-in yet.
+Speaking for the Ember.js core team, we are trying to get better at updating
+the community when plans have changed but the _new_ plan isn't locked in yet.
+So, consider this one of those situations.
+
+We know that the exact plan for Module Unification, [as laid out in the
+original RFC][mu], will need to change. How it changes is not yet certain,
+but we believe that some of the problems we wanted to solve with MU are
+better solved with template imports.
+
+But template imports are not a replacement of MU. They don't help with things
+like better isolation of an addon's services, or a more intuitive file system
+layout. Instead, we hope that template imports will better solve one aspect
+of MU, so its other benefits shine through even more clearly.
 
-So, consider this one of those situations. We know Module Unification, [as
-defined in the original MU RFC][mu], needs some changes before it's ready for
-prime time. We are still figuring out exactly what those changes are, and
-exactly the shape of the template imports design. Keep an eye on the [RFCs
-repo][rfcs], where we'll be sharing these proposals as soon as they're ready.
+If you are interested in following along and joining the design process, keep
+an eye on the [RFCs repo][rfcs], where we post new proposals as soon as
+they're ready.
 
 [mu]: https://emberjs.github.io/rfcs/0143-module-unification.html
 [rfcs]: https://github.com/emberjs/rfcs
 
-The MU RFC was merged in late 2016. It's fair to ask why implementing MU has
-taken this long, and why it took this long to realize we wanted to make
-changes. In the spirit of transparency and overcommunication, I wanted to
-share a little bit of the history and evolution of MU from my perspective.
+All that said, the MU RFC was merged in late 2016. It's fair to ask why
+implementing MU has taken this long, and why it took this long to realize we
+wanted to make changes. In the spirit of transparency and overcommunication,
+I wanted to share a little bit of the history and evolution of MU from my
+perspective.
 
 ## A Little History
 
@@ -124,11 +135,16 @@ place that sent us back to the drawing board.
 
 ### Namespaces and Scoped Packages
 
-One of the problems with the classic layout is that everything goes into one
-big global pool of names. So, for example, if your app has a component called
-`small-button` and you install an addon that also has a component called
-`small-button`, you have no way to tell Ember which one you mean when you
-type `{{small-button}}` in a template.
+Another problem with the classic layout is that everything goes into one
+big global pool of names.
+
+So, for example, Ember Data defines a service called `store` that you can
+inject into components and services. If you install another addon that also
+has a service called `store`, there's no easy way to use both.
+
+Similarly, if your app has a component called `small-button` and you install
+an addon that also has a component called `small-button`, you have no way to
+tell Ember which one you mean when you type `{{small-button}}` in a template.
 
 One of the key benefits of the MU design is that names are no longer global,
 but namespaced to the package where they come from. So, for example, if an
@@ -172,28 +188,47 @@ similar to JavaScript's `import` seemed like a promising solution.
 
 However, we immediately hit some challenges while exploring this idea.
 
-First, how much do we want to be like JavaScript? Should we create a
-Handlebars-flavored version of JavaScript imports? Something about this just
-felt _wrong_:
+The concept of a "component" in Ember isn't a singular thing, but the union
+of a template and a component class. With the component and template in
+separate files, it isn't clear which one you're supposed to import. Because
+of this, we wanted something where you would import a component by name
+(`my-component`), not a specific file like in JavaScript.
+
+Additionally, named imports (`import { thing }`) and wildcard imports
+(`import *`) didn't really translate either, given the template/class split.
+Another deviation from JavaScript.
+
+But there were important similarities, too. We wanted to find a syntax that
+would give users who already knew JavaScript an intuition about the
+similarities, while not making it look so similar that people would be misled
+into thinking it was literally the same thing.
+
+We tried to find a balance between these two constraints with a syntax that
+looked like this:
 
 ```hbs
-{{import small-component from "@my-company/ember-ui-library"}}
+{{use component-name from 'package-name'}}
 ```
 
-It reads like JavaScript, at the expense of being incoherent when read as
-Handlebars, whose syntax is a functional programming language in the spirit
-of Lisp. We seriously considered it, but couldn't get past additional
-problems like how to accommodate named exports (`import { thing }`) and
-wildcard imports (`import *`).
+We hoped that it looked similar enough to JavaScript's `import` syntax to
+give you a clue about what it was doing, but by adopting the `use` keyword
+instead of `import`, signal that this was not exactly the same as JavaScript
+modules.
+
+Matthew Beale poured significant time into capturing all of these conflicting
+constraints in the [Module Unification Packages RFC][mu-pkg], but, even after
+months of discussion, we couldn't come to consensus and the RFC was never
+merged.
 
-Next, we thought about literally embedding JavaScript in templates, but again
-there were syntactic incompatibilities between Handlebars and JavaScript.
-Given the requirement that component names contain a dash (`-`) character,
-but JavaScript identifiers aren't allowed to contain dashes, what exactly do
-you type? `import small-component from '@my-company/ember-ui-library'` isn't
-valid JavaScript.
+[mu-pkg]: https://github.com/emberjs/rfcs/pull/367
 
-We still felt stuck.
+Despite everyone agreeing this was an urgent problem, we couldn't convince
+ourselves that having different module systems for JavaScript and templates
+was a viable solution. Unfortunately, there wasn't an obvious alternative
+plan, and not having an answer meant MU was indefinitely blocked until we
+could figure out this last piece of the puzzle.
+
+We felt stuck.
 
 ### Real-World Feedback
 
@@ -248,14 +283,15 @@ In practice, though, we ran into a few challenges:
 2. Similarly, ecosystem tools don't understand MU. We have to build custom
    integrations to get things like "Go to Definition" to work in IDEs or code
    splitting to work in webpack, that other libraries get for free.
-3. JavaScript files in Ember use native module syntax anyway, which doesn't
-   go through the MU system, adding to the confusion. Having one system in
-   a component's JavaScript and another in its template is not ideal.
-4. When file names are so meaningful, it can be frustrating to figure out how
-   to tell MU ignore a file that _isn't_ meaningful. Tasks that are trivial
-   in other programming environments, such as grouping related components
-   together, can easily turn into a battle where your build starts erroring
-   because you can't figure out the right incantation of the MU rules.
+3. JavaScript files in Ember use module syntax, which doesn't go through the
+   MU system, adding to the confusion. Having one system in a component's
+   JavaScript and another in its template is not ideal.
+4. When file names and locations are so meaningful, it can be frustrating
+   if you want to create a file that isn't part of the MU world. Tasks that
+   are normally trivial, such as extracting utility functions into a separate
+   file or grouping related files together in a directory, can easily turn
+   into a battle where your build starts erroring because you're not playing
+   by the MU rules.
 
 ### A Personal Anecdote
 
@@ -275,11 +311,11 @@ different experience that turned into an hours-long slog. And despite all the
 great things it _does_ do, MU doesn't really have a way to do this kind of
 lightweight grouping.
 
-We could have extracted the SVG icon components into a separate package. We
-could have tried to create a higher-order component that wrapped all of the
-child icon components. We could have found a workaround. But it seemed
-ridiculous to burn so much time looking for a "workaround" to perform a task
-that felt like it should have been (and was, in Preact) trivial.
+We could have found a workaround. We could have extracted the SVG icon
+components into a separate package, or created a higher-order component that
+wrapped all of the child icon components. But it seemed ridiculous to burn so
+much time looking for a "workaround" to perform a task that felt like it
+should have been (and was, in Preact) trivial.
 
 I knew, intellectually, the benefits of MU. I knew how carefully it was
 designed to enforce structure and consistency as your application grew and
@@ -297,34 +333,36 @@ we couldn't make progress on the scoped package problem, but I was even more
 overwhelmed trying to figure out what, if anything, to do about the negative
 experiences my co-workers had had when using MU.
 
-Revisiting a design you've been working on for so long is painful, especially
-in cases like this where the majority of the work is already complete. We
-felt like we just had to solve the scoped package problem and we'd finally be
-done.
+Discovering problems in a design you've been working on for so long is
+painful, especially in cases like this where the majority of the work was
+already complete, and we thought we were so close to the finish line.
 
-Programming language and API design is hard. Really hard. Sometimes I read
-old RFCs and marvel at how obvious the design seems now, after the weeks,
-months, or years we spent teasing it out from the millions of possibilities
-in front of us.
+Programming language and API design is really hard. Sometimes I read old RFCs
+and marvel at how obvious the design seems now, after the weeks, months, or
+years we spent teasing it out from the millions of possibilities in front of
+us.
 
 When you're trying to balance so many competing constraints, sometimes a
 small change is all it takes to get you out of a design conundrum you've
 struggled with for months. In this case, that change was angle bracket
 component invocation.
 
-As I mentioned above, it seemed obvious we couldn't use JavaScript for
-template imports because components had to have a dash in their name. If we
-wanted to import identifiers with a dash in the name, we'd have to invent our
-own syntax.
+One reason we didn't think we could use JavaScript imports in templates was
+because components had to have a dash in their name. Unfortunately, dashes
+aren't valid in JavaScript identifiers, so something like `import
+some-component from './some-component'` produces a syntax error.
 
 Angle bracket components, on the other hand, start with a capital letter to
-differentiate themselves from normal HTML tags, so they use PascalCase—and no
-dash. As the Ember community started using angle bracket syntax, early
-feedback was very positive. All of a sudden, JavaScript import syntax was
-back on the table.
+disambiguate themselves from normal HTML tags: `<MyComponent />` instead of
+`{{my-component}}`. Most importantly, there's no dash.
+
+As the Ember community started using angle bracket syntax, early feedback was
+very positive. All of a sudden, JavaScript import syntax was back on the
+table.
 
-With the renewed excitement about template imports, it was a good time to
-bring up the ergonomic concerns about MU.
+With the renewed interest in exploring JavaScript imports for templates, it
+also gave us a good opportunity to try to address the ergonomic problems
+people had reported when trying MU.
 
 Without template imports, we had to rely on MU to resolve component names,
 meaning the files in the `src/ui/components` directory had to follow strict
@@ -333,27 +371,26 @@ disk they want. We can skip resolving components through MU altogether, and
 let Ember users organize their component files however they want.
 
 As frustrating as it was at the time, the inability to make progress on MU
-may have been a blessing in disguise. It gave us time to land angle bracket
-components, which allowed template imports to seem feasible again, which
-allowed us to both solve the scoped package problem while loosening the
-strictest MU rules.
-
-I think the deadend we found ourselves in was a sign from the universe that
-we needed to wait for the better design that was just around the corner. Time
-will tell, but I think template imports are a much, much better design. And
-this process also pushed us to explore single-file components, which I think
-will be a surprisingly big productivity improvement for Ember developers.
+may have been a blessing in disguise. It gave us time to implement angle
+bracket syntax for components, which allowed template imports to seem
+feasible again—which meant that we now had a solution that seemed to address
+both the scoped package problem and the ergonomics problem.
 
-I want to be clear: the is all just one person's recollection of events. The
-reality of technical design is messy and feels a lot more like going around
-in circles than the nice, clean, linear sequence I've presented here.
+I believe the dead-end we found ourselves in was a sign from the universe
+that something better was just around the corner. Time will tell, but my
+hunch is that template imports solve some important problems much more elegantly
+than what we had before.
+
+This process also pushed us to explore single-file components, which I think
+will be a surprisingly big productivity improvement for Ember developers.
 
 ### What's Next
 
-I recently posted the [SFC & Template Import Primitives
-RFC](https://github.com/emberjs/rfcs/pull/454), which is the first of several
-RFCs describing changes to MU or new features that complement MU. You should
-see more RFCs related to this topic in the coming weeks.
+Hopefully, this post helps provide some context about the state of MU. Of
+course, what I've written here is my personal, imperfect recollection of
+events, simplified for clarity. The reality of technical design is messy and
+feels a lot more like going around in circles than the tidy sequence I've
+presented here.
 
 I will also mention that, as a project, I think we've dramatically improved
 how we design, implement, validate, and iterate on features since we
@@ -364,16 +401,27 @@ upfront design and implementation before we had any feedback from real users.
 Nowadays, I think we're a lot better about making sure RFCs are relatively
 small and focused on doing one thing and doing it well. We also tend to
 prioritize exposing hooks or other primitives that let us test out new ideas
-in addons. This allows us to improve designs based on real world feedback,
+in addons. This allows us to improve designs based on early feedback,
 without the strict stability requirements that come with landing something in
 the framework proper.
 
 This has worked well for things like `ember-decorators` and
 `@glimmer/component`, where real world feedback and the ability to make
 breaking changes based on that feedback was critical. I'm hopeful that a
-similar strategy for single-file components will be just as successful.
+similar strategy for template imports will be just as successful.
+
+I recently posted the [SFC & Template Import Primitives
+RFC](https://github.com/emberjs/rfcs/pull/454), which is the first of several
+RFCs describing changes to MU or new features that complement MU. You should
+see more RFCs related to this topic in the coming weeks.
+
+My sincere thanks to everyone who has worked so hard on MU, template imports,
+and other related efforts. I'm proud to be part of a community that refuses
+to charge ahead with something we know isn't right. Ember's longevity is, at
+least in part, explained by our willingness to make these kinds of hard
+decisions.
 
-I'm so excited about Ember, our technical vision, and the newfound energy in
-our community. In 2019, a thriving Ember is more important for the web than
-ever. Thank you for being a part of our community, and I hope to see you at
+I'm so excited about Ember, our roadmap, and the newfound energy in our
+community. In 2019, a thriving Ember is more important for the web than ever.
+Thank you for being a part of our community, and I hope to see you at
 EmberConf in a few weeks. It's gonna be a good one.
\ No newline at end of file

From 05c987310e8cc4f97e3b6a9fd6ce8d5f3452d573 Mon Sep 17 00:00:00 2001
From: Robert Jackson <me@rwjblue.com>
Date: Thu, 7 Mar 2019 17:43:52 -0500
Subject: [PATCH 4/7] Apply suggestions from code review

Co-Authored-By: rwjblue <me@rwjblue.com>
---
 .../2019-03-02-update-on-module-unification-and-octane.md   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index 9d3d0299e4..c1ee5fc12a 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -63,13 +63,13 @@ While the Ember.js core team has reached consensus that template imports are
 the path forward, please note that the syntax shown in the examples above is
 hypothetical. While I'm personally a fan of the `<template>` tag syntax shown
 here, others are not, and details like this are still being hammered out in
-the RFC process and are highly likely to change.
+the [RFC process](https://github.com/emberjs/rfcs/pull/454) and are highly likely to change.
 
 Speaking for the Ember.js core team, we are trying to get better at updating
 the community when plans have changed but the _new_ plan isn't locked in yet.
 So, consider this one of those situations.
 
-We know that the exact plan for Module Unification, [as laid out in the
+We know that the exact plan for Module Unification (MU), [as laid out in the
 original RFC][mu], will need to change. How it changes is not yet certain,
 but we believe that some of the problems we wanted to solve with MU are
 better solved with template imports.
@@ -424,4 +424,4 @@ decisions.
 I'm so excited about Ember, our roadmap, and the newfound energy in our
 community. In 2019, a thriving Ember is more important for the web than ever.
 Thank you for being a part of our community, and I hope to see you at
-EmberConf in a few weeks. It's gonna be a good one.
\ No newline at end of file
+[EmberConf](https://emberconf.com) in a few weeks. It's gonna be a good one.

From 3d9dc6f3402ce1e27299617d8565cbcb8033a4ee Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Fri, 8 Mar 2019 20:34:55 -0500
Subject: [PATCH 5/7] Update forward-looking statements based on attorney
 counsel

---
 ...update-on-module-unification-and-octane.md | 355 +++++++++++-------
 1 file changed, 212 insertions(+), 143 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index c1ee5fc12a..b618950b30 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -1,5 +1,5 @@
 ---
-title: 'Update on Module Unification & Octane'
+title: 'Update on Module Unification'
 author: Tom Dale
 tags: Recent Posts, 2019, Ember Octane
 responsive: true
@@ -12,115 +12,111 @@ developer experience. It's crucial that we get both the technical and
 ergonomic details right. I wanted to provide an update about Module
 Unification and our plans for the file structure in Ember Octane.
 
-In short, we intend to make templates play nicely with JavaScript, so you can
-use the `import` feature you already know and love. By having components and
-helpers be modules you can import, we can simplify Module Unification so it's
-easier to learn and use.
+**In short, we do not plan to ship Module Unification in Octane**. Instead,
+Octane will ship with today's file system layout, with two changes:
 
-Here's an example of what I think template imports could look like:
+* Co-located components and templates
+* Support for nested components in `<AngleBracket />` invocation syntax
 
-```js
-// src/ui/components/blog-post.gbs
+### Co-located Components and Templates
 
-import Component from '@glimmer/component';
-import UserProfile from './user-profile';
-import UserIcon from './icons/user';
+Today, component classes and their associated templates are quite spread out.
+If you have a component in `app/components/user-profile.js`, its template
+lives in `app/templates/components/user-profile.hbs`. This can make
+navigating between the two files time-consuming.
 
-export class BlogPost extends Component {
-  blog = { title: 'Coming soon in Octane', authorId: '1234' }
+In Octane, we will switch to putting a component's JavaScript and template
+file in the same directory.
 
-  <template>
-    <h1>{{this.blog.title}}</h1>
-    <UserIcon />
-    <UserProfile @userId={{this.blog.authorId}} />
-  </template>
-}
-```
+For example, if you generate a new component called `user-profile` with
+`ember generate component user-profile`, the blueprint will produce these
+files:
 
-Here, we've imported two components—`UserProfile` and `UserIcon`—like we
-would any other JavaScript module. We've also defined the component's
-template in JavaScript, placing it in in a template tag within the class
-body.
+* `app/components/user-profile/component.js`
+* `app/components/user-profile/template.hbs`
+* `tests/integration/components/user-profile-test.js`
+
+This co-located `component.js` and `template.hbs` layout actually already
+works in Ember apps today, so the only change required is to update the
+default component blueprint.
 
-For templates that aren't associated with a component (such as route
-templates), we could allow template tags to be exported from JavaScript as
-well:
+### Angle Brackets with Nested Components
 
-```js
-// src/ui/routes/application.gbs
+Because Octane apps will continue with today's file system layout, we also
+wanted to address the largest blocker to `<AngleBracket />` syntax adoption
+today: components nested inside other directories.
 
-import NavBar from '../components/NavBar';
+For example, if you have a component located at
+`app/components/icons/download-icon.js` (i.e., nested inside an `icons`
+directory), you can invoke it with curly invocation syntax like this:
 
-export default <template>
-  <NavBar @darkMode={{true}} />
-  <main>
-    {{outlet}}
-  </main>
-</template>;
+```handlebars
+{{icons/download-icon}}
 ```
 
-While the Ember.js core team has reached consensus that template imports are
-the path forward, please note that the syntax shown in the examples above is
-hypothetical. While I'm personally a fan of the `<template>` tag syntax shown
-here, others are not, and details like this are still being hammered out in
-the [RFC process](https://github.com/emberjs/rfcs/pull/454) and are highly likely to change.
+However, it's not possible to invoke the same nested component with angle
+bracket syntax without resorting to clunky workarounds.
 
-Speaking for the Ember.js core team, we are trying to get better at updating
-the community when plans have changed but the _new_ plan isn't locked in yet.
-So, consider this one of those situations.
+As proposed in the [Nested Invocations in Angle Bracket Syntax
+RFC][nested-angle-brackets], we plan to address this by adding support for
+nested components via the `::` separator.
 
-We know that the exact plan for Module Unification (MU), [as laid out in the
-original RFC][mu], will need to change. How it changes is not yet certain,
-but we believe that some of the problems we wanted to solve with MU are
-better solved with template imports.
+[nested-angle-brackets]: https://github.com/emberjs/rfcs/pull/457
 
-But template imports are not a replacement of MU. They don't help with things
-like better isolation of an addon's services, or a more intuitive file system
-layout. Instead, we hope that template imports will better solve one aspect
-of MU, so its other benefits shine through even more clearly.
+With this proposal, the component described above could be invoked with angle
+bracket syntax like this:
 
-If you are interested in following along and joining the design process, keep
-an eye on the [RFCs repo][rfcs], where we post new proposals as soon as
-they're ready.
+```handlebars
+<Icons::DownloadIcon />
+```
 
-[mu]: https://emberjs.github.io/rfcs/0143-module-unification.html
-[rfcs]: https://github.com/emberjs/rfcs
+Because both of these changes are quite small, they can be implemented
+quickly without requiring us to delay the Ember Octane release.
+
+## Status of Module Unification
+
+Given that the Module Unification RFC was merged in late 2016, and we talked
+about shipping Module Unification in the [2018 Roadmap RFC][roadmap-rfc],
+it's fair to ask what happened and why we're making this decision now.
+
+[roadmap-rfc]: https://emberjs.github.io/rfcs/0364-roadmap-2018.html
 
-All that said, the MU RFC was merged in late 2016. It's fair to ask why
-implementing MU has taken this long, and why it took this long to realize we
-wanted to make changes. In the spirit of transparency and overcommunication,
-I wanted to share a little bit of the history and evolution of MU from my
-perspective.
+Heads up: this post gets long and detailed, so if you are only care about the
+plan going forward, you can safely skip the rest.
 
-## A Little History
+In the spirit of transparency and overcommunication, though, I wanted to
+share a little bit of the history and evolution of MU from my perspective.
 
-Today, Ember apps use the "classic" file layout by default. While this layout
-has served us well, it also has several shortcomings.
+Let's call the file system layout that Ember apps use today the "classic"
+layout. While this structure has served us well, it also has several
+shortcomings.
 
-Because files are grouped by type, a component's template resides in one
-directory (`app/templates/components`) while its JavaScript class resides in
-another (`app/components`). Jumping between these two directories as they
-grow can be frustrating, especially given how frequently Ember developers
-need to switch back and forth between component class and template.
+As mentioned above, related files (like a component and its template) being
+separated from each other can be frustrating. While we are planning to
+address this in Octane for components, there are other kinds of files that
+you might want to group together also. For example, you may want an Ember
+Data model and its serializer to be co-located in the same directory.
 
 Early on, Ember CLI implemented an experimental "pods" layout that grouped
-files by name rather than by kind. So, for example, a component's JavaScript
-and template file would be grouped together in `app/component-name/`, as
-`component.js` and `template.hbs` respectively.
+files by name rather than by kind. So, for example, a `User` model and its
+serializer would be grouped together in `app/user/`, as `model.js` and
+`serializer.js` respectively.
 
-User feedback was that pods felt more productive than the classic layout.
-However, pods had several problems that needed to be addressed before it could
-be enabled by default.
+Feedback from the community was that pods felt more productive than the
+classic layout. However, pods had several problems that needed to be
+addressed before it could be enabled by default.
 
 The effort to address the design flaws of pods led to the [Module Unification
 RFC][mu], a ground-up rethink of how the file system should work in Ember
 apps. Importantly, this design grappled with overhauling Ember's resolver and
-dependency injection systems, which was as much or more important than
-deciding the particular file system layout.
+dependency injection systems as well, which was just as important as
+shuffling around where particular files went on disk.
+
+[mu]: https://emberjs.github.io/rfcs/0143-module-unification.html
 
 The MU RFC was merged at the end of 2016, but new Ember apps are still
-generated with the classic layout. So, why is that? Why can't we flip the
-switch on enabling Module Unification-style layout by default today?
+generated with the classic layout. So, why can't we flip the switch on
+enabling Module Unification-style layout by default today?
 
 Remember that MU described not just a new file system but a significant
 overhaul of Ember's resolver. Implementing MU was a **huge** initiative that,
@@ -129,14 +125,20 @@ large scope, and thanks to the incredible amount of time and energy our
 community devoted to the work, MU implementation has made great progress, and
 nearly everything needed to make Module Unification work has landed in Ember.
 
-_Nearly_ everything. There's one last major piece needed to ship, and while
-we were working on implementing MU, shifts in the JavaScript ecosystem took
-place that sent us back to the drawing board.
+**Nearly** everything. When we merged the Roadmap RFC last year, there was one
+last major piece of MU that still needed to be designed: component
+namespacing, or how to refer to components that come from other addons in
+templates.
+
+While we had a plan, a shift in the JavaScript ecosystem sent us back to the
+drawing board. And the harder we worked on solving this last piece, the more
+we realized that fundamental aspects of the overall design needed to be
+rethought.
 
 ### Namespaces and Scoped Packages
 
-Another problem with the classic layout is that everything goes into one
-big global pool of names.
+Besides files being spread out, another problem with the classic layout is
+that everything goes into one big global pool of names.
 
 So, for example, Ember Data defines a service called `store` that you can
 inject into components and services. If you install another addon that also
@@ -149,32 +151,31 @@ tell Ember which one you mean when you type `{{small-button}}` in a template.
 One of the key benefits of the MU design is that names are no longer global,
 but namespaced to the package where they come from. So, for example, if an
 npm package called `ember-ui-library` contains a component called
-`small-button`, I would refer to it in my template as
+`small-button`, the MU RFC proposed referring to it in your template as
 `{{ember-ui-library::small-button}}`.
 
-This worked pretty well, with the downside that it could get quite verbose.
-This was especially true when components were invoked with a block:
+This worked pretty well, with the downside that it could sometimes be
+verbose, particularly when components were invoked with a block:
 
-```hbs
+```handlebars
 {{#ember-ui-library::small-button}}
   ...
 {{/ember-ui-library::small-button}}
 ```
 
-Around the same time we were designing MU, [npm announced support for scoped
-package names][scoped-packages]. Prior to this change, npm package names were
-limited to alphanumeric characters and dashes. With this change, however,
-packages could now start with an `@` and be prefixed with a user or
-organization, like `@glimmer/component`.
+Around the same time we were designing MU, however, [npm announced support
+for scoped package names][scoped-packages]. Prior to this change, npm package
+names were limited to alphanumeric characters and dashes. Now, though,
+packages could start with an `@` and contain a `/`, like
+`@glimmer/component`.
 
 [scoped-packages]: https://blog.npmjs.org/post/116936804365/solving-npms-hard-problem-naming-packages
 
 While namespaced component invocations pushed the limits of verbosity,
 combining them with scoped packages blew past that limit. We simply could not
-bring ourselves to accept a syntax that commonly produced monstrosities like
-this:
+bring ourselves to accept a syntax that commonly produced code like this:
 
-```hbs
+```handlebars
 {{#@my-company/ember-ui-library::small-button}}
   ...
 {{/@my-company/ember-ui-library::small-button}}
@@ -182,11 +183,13 @@ this:
 
 While Ember had been using it for years, around this time JavaScript module
 syntax (`import Post from './post'`) started gaining significant traction in
-the wider ecosystem. After scoped npm packages scuttled our original plan for
-namespaced components, we went back to the drawing board, and something
-similar to JavaScript's `import` seemed like a promising solution.
+the wider ecosystem, along with tools like webpack that could use these
+modules to perform code splitting.
 
-However, we immediately hit some challenges while exploring this idea.
+After scoped npm packages scuttled our original plan for namespaced
+components, we went back to the drawing board, and something similar to
+JavaScript's `import` seemed like a promising solution. However, we
+immediately hit some challenges while exploring this idea.
 
 The concept of a "component" in Ember isn't a singular thing, but the union
 of a template and a component class. With the component and template in
@@ -206,7 +209,7 @@ into thinking it was literally the same thing.
 We tried to find a balance between these two constraints with a syntax that
 looked like this:
 
-```hbs
+```handlebars
 {{use component-name from 'package-name'}}
 ```
 
@@ -326,8 +329,6 @@ while the Preact app had several inconsistently-followed conventions.)
 But I never forgot how viscerally bad it felt to have my co-workers fight so
 hard to do something that felt like it should be so easy.
 
-### The Path Forward
-
 So this was the status quo last year. We were all incredibly frustrated that
 we couldn't make progress on the scoped package problem, but I was even more
 overwhelmed trying to figure out what, if anything, to do about the negative
@@ -338,18 +339,18 @@ painful, especially in cases like this where the majority of the work was
 already complete, and we thought we were so close to the finish line.
 
 Programming language and API design is really hard. Sometimes I read old RFCs
-and marvel at how obvious the design seems now, after the weeks, months, or
-years we spent teasing it out from the millions of possibilities in front of
-us.
+and marvel at how obvious the solution seems now, in contrast to the weeks,
+months, or years I know it took to tease it out from the millions of possible
+alternatives.
 
 When you're trying to balance so many competing constraints, sometimes a
 small change is all it takes to get you out of a design conundrum you've
 struggled with for months. In this case, that change was angle bracket
 component invocation.
 
-One reason we didn't think we could use JavaScript imports in templates was
-because components had to have a dash in their name. Unfortunately, dashes
-aren't valid in JavaScript identifiers, so something like `import
+One thing making JavaScript imports difficult to use with templates was the
+constraint that components had to have a dash in their name. Unfortunately,
+dashes aren't valid in JavaScript identifiers, so something like `import
 some-component from './some-component'` produces a syntax error.
 
 Angle bracket components, on the other hand, start with a capital letter to
@@ -360,31 +361,105 @@ As the Ember community started using angle bracket syntax, early feedback was
 very positive. All of a sudden, JavaScript import syntax was back on the
 table.
 
-With the renewed interest in exploring JavaScript imports for templates, it
-also gave us a good opportunity to try to address the ergonomic problems
-people had reported when trying MU.
+### The Path Forward: Template Imports
+
+Speaking for the Ember.js core team, we are trying to get better at updating
+the community when plans have changed but the new plan isn't fully locked in
+yet. So, consider this one of those situations.
+
+We know that the exact plan for Module Unification (MU), as described in the
+original RFC, will need to change. How it changes is not yet certain,
+but we believe that some of the problems we wanted to solve with MU are
+better solved with template imports.
+
+With template imports, we intend to make templates play nicely with
+JavaScript, so you can use the `import` feature you already know and love. By
+having components and helpers be modules you can import, we can eliminate the
+most complex parts of Module Unification so it's easier to learn and use.
+
+We recently posted the [SFC & Template Imports RFC][template-imports-rfc],
+which describes some of the low-level APIs needed in Ember to make template
+imports possible.
+
+[template-imports-rfc]: https://github.com/emberjs/rfcs/pull/454
+
+Learning from past mistakes, this RFC focuses on the primitives so we can
+quickly experiment, get feedback, and iterate on template import proposals in
+addons, before stabilizing them in the core framework.
+
+While the Ember.js core team has reached consensus that template imports are
+the intended path forward, please note that the current RFC only covers
+low-level primitives, not the API that would be used by Ember developers to
+author templates.
+
+Here is one example of a **very hypothetical** template imports syntax:
+
+```javascript
+// src/ui/components/blog-post.gbs
+
+import Component from '@glimmer/component';
+
+import UserProfile from './user-profile';
+import UserIcon from './icons/user';
+
+export class BlogPost extends Component {
+  blog = { title: 'Coming soon in Octane', authorId: '1234' }
+
+  <template>
+    <h1>{{this.blog.title}}</h1>
+    <UserIcon />
+    <UserProfile @userId={{this.blog.authorId}} />
+  </template>
+}
+```
+
+Here, we've imported two components—`UserProfile` and `UserIcon`—like we
+would any other JavaScript module. We've also defined the component's
+template in JavaScript, placing it in in a template tag within the class
+body.
+
+The exact syntax is up in the air and will almost certainly be different from
+this example. The benefit of exposing the low-level primitives first is that
+we can try out multiple competing designs relatively easily before comitting.
+And if you don't like what we eventually decide on, you can build an
+alternative that is just as stable as the default implementation.
+
+But note that template imports are not a replacement for MU. They don't help
+with things like better isolation of an addon's services, or a more intuitive
+file system layout. Instead, we hope that template imports will better solve
+one aspect of MU, so the overall design can be simplified and its benefits
+can shine through more clearly.
+
+Template imports also give us a good opportunity to try to address the
+ergonomic problems people reported when trying MU.
 
 Without template imports, we had to rely on MU to resolve component names,
 meaning the files in the `src/ui/components` directory had to follow strict
-rules. But _with_ template imports, users can just tell us which module on
+rules. But **with** template imports, users can just tell us which module on
 disk they want. We can skip resolving components through MU altogether, and
 let Ember users organize their component files however they want.
 
 As frustrating as it was at the time, the inability to make progress on MU
 may have been a blessing in disguise. It gave us time to implement angle
 bracket syntax for components, which allowed template imports to seem
-feasible again—which meant that we now had a solution that seemed to address
-both the scoped package problem and the ergonomics problem.
+feasible again—which means we now have a solution that seems to address both
+the scoped package problem and the ergonomics problem. Even better, template
+imports make things like treeshaking and code-splitting in
+[Embroider][embroider] much easier.
+
+[embroider]: https://github.com/embroider-build/embroider
 
 I believe the dead-end we found ourselves in was a sign from the universe
 that something better was just around the corner. Time will tell, but my
-hunch is that template imports solve some important problems much more elegantly
-than what we had before.
-
-This process also pushed us to explore single-file components, which I think
-will be a surprisingly big productivity improvement for Ember developers.
+hunch is that template imports solve these important problems much more
+elegantly than what we had before. This process also pushed us to explore
+single-file components, which I think will be a surprisingly big productivity
+improvement for Ember developers.
 
-### What's Next
+While we're excited about template imports, we want to keep our promise to
+finish what we started. We are prioritizing Ember Octane and making sure that
+our first edition is a polished, cohesive experience. Only once Octane is out
+the door will we turn our attention to new initiatives like template imports.
 
 Hopefully, this post helps provide some context about the state of MU. Of
 course, what I've written here is my personal, imperfect recollection of
@@ -399,27 +474,21 @@ proposals from the "mega-RFC" era, where we had a tendency to do a ton of
 upfront design and implementation before we had any feedback from real users.
 
 Nowadays, I think we're a lot better about making sure RFCs are relatively
-small and focused on doing one thing and doing it well. We also tend to
-prioritize exposing hooks or other primitives that let us test out new ideas
-in addons. This allows us to improve designs based on early feedback,
-without the strict stability requirements that come with landing something in
-the framework proper.
-
-This has worked well for things like `ember-decorators` and
-`@glimmer/component`, where real world feedback and the ability to make
-breaking changes based on that feedback was critical. I'm hopeful that a
-similar strategy for template imports will be just as successful.
-
-I recently posted the [SFC & Template Import Primitives
-RFC](https://github.com/emberjs/rfcs/pull/454), which is the first of several
-RFCs describing changes to MU or new features that complement MU. You should
-see more RFCs related to this topic in the coming weeks.
-
-My sincere thanks to everyone who has worked so hard on MU, template imports,
-and other related efforts. I'm proud to be part of a community that refuses
-to charge ahead with something we know isn't right. Ember's longevity is, at
-least in part, explained by our willingness to make these kinds of hard
-decisions.
+small and focused on doing one thing. We also tend to prioritize exposing
+hooks or other primitives that let us test out new ideas in addons. This
+allows us to improve designs based on early feedback, without the strict
+stability requirements that come with landing something in the framework
+proper.
+
+This has worked well for things like `ember-decorators` and Glimmer
+components, where real world feedback and the ability to make breaking
+changes based on that feedback was critical. I'm hopeful that a similar
+strategy for template imports will be just as successful.
+
+My sincere thanks to everyone who has worked so hard on MU and related
+efforts. I'm proud to be part of a community that refuses to charge ahead
+with something we know isn't right. Ember's longevity is, at least in part,
+explained by our willingness to make these kinds of hard decisions.
 
 I'm so excited about Ember, our roadmap, and the newfound energy in our
 community. In 2019, a thriving Ember is more important for the web than ever.

From d2a3bf3d3aba5f4ba5e650317233a1c20954d21c Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Mon, 11 Mar 2019 16:19:28 -0400
Subject: [PATCH 6/7] Incorporate feedback from @chancancode

---
 ...update-on-module-unification-and-octane.md | 75 +++++++++++--------
 1 file changed, 44 insertions(+), 31 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index b618950b30..edee7c4e7f 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -38,7 +38,8 @@ files:
 
 This co-located `component.js` and `template.hbs` layout actually already
 works in Ember apps today, so the only change required is to update the
-default component blueprint.
+default component blueprint. We will also provide a codemod that can
+automatically re-organize your component files to follow this structure.
 
 ### Angle Brackets with Nested Components
 
@@ -151,11 +152,8 @@ tell Ember which one you mean when you type `{{small-button}}` in a template.
 One of the key benefits of the MU design is that names are no longer global,
 but namespaced to the package where they come from. So, for example, if an
 npm package called `ember-ui-library` contains a component called
-`small-button`, the MU RFC proposed referring to it in your template as
-`{{ember-ui-library::small-button}}`.
-
-This worked pretty well, with the downside that it could sometimes be
-verbose, particularly when components were invoked with a block:
+`small-button`, the MU RFC proposed referring to it in your template like
+this:
 
 ```handlebars
 {{#ember-ui-library::small-button}}
@@ -171,9 +169,9 @@ packages could start with an `@` and contain a `/`, like
 
 [scoped-packages]: https://blog.npmjs.org/post/116936804365/solving-npms-hard-problem-naming-packages
 
-While namespaced component invocations pushed the limits of verbosity,
-combining them with scoped packages blew past that limit. We simply could not
-bring ourselves to accept a syntax that commonly produced code like this:
+Component invocations with scoped packages blew past the verbosity limit. We
+simply could not bring ourselves to accept a syntax that commonly produced
+code like this:
 
 ```handlebars
 {{#@my-company/ember-ui-library::small-button}}
@@ -181,6 +179,10 @@ bring ourselves to accept a syntax that commonly produced code like this:
 {{/@my-company/ember-ui-library::small-button}}
 ```
 
+We also had concerns that this was confusing to scan visually, considering
+that `@` already means a component argument and `/` already means a closing
+tag.
+
 While Ember had been using it for years, around this time JavaScript module
 syntax (`import Post from './post'`) started gaining significant traction in
 the wider ecosystem, along with tools like webpack that could use these
@@ -197,14 +199,11 @@ separate files, it isn't clear which one you're supposed to import. Because
 of this, we wanted something where you would import a component by name
 (`my-component`), not a specific file like in JavaScript.
 
-Additionally, named imports (`import { thing }`) and wildcard imports
-(`import *`) didn't really translate either, given the template/class split.
-Another deviation from JavaScript.
-
-But there were important similarities, too. We wanted to find a syntax that
-would give users who already knew JavaScript an intuition about the
-similarities, while not making it look so similar that people would be misled
-into thinking it was literally the same thing.
+But despite the differences, the overall concept of importing modules was
+similar. We wanted to find a syntax that would give users who already knew
+JavaScript an intuition about the similarities, while not making it look so
+similar that people would be misled into thinking it was literally the same
+thing.
 
 We tried to find a balance between these two constraints with a syntax that
 looked like this:
@@ -394,16 +393,35 @@ author templates.
 
 Here is one example of a **very hypothetical** template imports syntax:
 
-```javascript
+```hbs
+---
+import UserProfile from './user-profile';
+import UserIcon from './icons/user';
+---
+<h1>{{this.blog.title}}</h1>
+<UserIcon />
+<UserProfile @userId={{this.blog.authorId}} />
+```
+
+The syntax is up in the air and will almost certainly be different from this
+example. Regardless, it shows the benefit of template imports clearly: we've
+imported two components—`UserProfile` and `UserIcon`—just like how we would
+refer to any other JavaScript module. This makes it very easy for
+everyone—from developer who are new to Ember, to IDEs, and other tooling in
+the JavaScript ecosystem`—to understand what came from where.
+
+You can even imagine an (again, **very hypothetical**) single-file component
+format that places the template right within the component's class. Here, a
+unified imports solution feels especially natural:
+
+```js
 // src/ui/components/blog-post.gbs
 
 import Component from '@glimmer/component';
-
-import UserProfile from './user-profile';
 import UserIcon from './icons/user';
 
 export class BlogPost extends Component {
-  blog = { title: 'Coming soon in Octane', authorId: '1234' }
+  blog = { title: 'Coming soon in Octane', authorId: '1234' };
 
   <template>
     <h1>{{this.blog.title}}</h1>
@@ -413,16 +431,11 @@ export class BlogPost extends Component {
 }
 ```
 
-Here, we've imported two components—`UserProfile` and `UserIcon`—like we
-would any other JavaScript module. We've also defined the component's
-template in JavaScript, placing it in in a template tag within the class
-body.
-
-The exact syntax is up in the air and will almost certainly be different from
-this example. The benefit of exposing the low-level primitives first is that
-we can try out multiple competing designs relatively easily before comitting.
-And if you don't like what we eventually decide on, you can build an
-alternative that is just as stable as the default implementation.
+Again, the exact syntax is up in the air and will almost certainly be
+different from this example. The benefit of exposing the low-level primitives
+first is that we can try out multiple competing designs relatively easily
+before comitting. And if you don't like what we eventually decide on, you can
+build an alternative that is just as stable as the default implementation.
 
 But note that template imports are not a replacement for MU. They don't help
 with things like better isolation of an addon's services, or a more intuitive

From aa737a6f0e10159247d9f7f24f72aae13da03b2e Mon Sep 17 00:00:00 2001
From: Tom Dale <tom@tomdale.net>
Date: Mon, 11 Mar 2019 16:38:27 -0400
Subject: [PATCH 7/7] Removes description of classic layout tweak

---
 ...update-on-module-unification-and-octane.md | 55 +++++--------------
 1 file changed, 15 insertions(+), 40 deletions(-)

diff --git a/source/blog/2019-03-02-update-on-module-unification-and-octane.md b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
index edee7c4e7f..5de843ca42 100644
--- a/source/blog/2019-03-02-update-on-module-unification-and-octane.md
+++ b/source/blog/2019-03-02-update-on-module-unification-and-octane.md
@@ -13,39 +13,12 @@ ergonomic details right. I wanted to provide an update about Module
 Unification and our plans for the file structure in Ember Octane.
 
 **In short, we do not plan to ship Module Unification in Octane**. Instead,
-Octane will ship with today's file system layout, with two changes:
+Octane will ship with today's file system layout, with one change: support
+for nested components in `<AngleBracket />` invocation syntax
 
-* Co-located components and templates
-* Support for nested components in `<AngleBracket />` invocation syntax
-
-### Co-located Components and Templates
-
-Today, component classes and their associated templates are quite spread out.
-If you have a component in `app/components/user-profile.js`, its template
-lives in `app/templates/components/user-profile.hbs`. This can make
-navigating between the two files time-consuming.
-
-In Octane, we will switch to putting a component's JavaScript and template
-file in the same directory.
-
-For example, if you generate a new component called `user-profile` with
-`ember generate component user-profile`, the blueprint will produce these
-files:
-
-* `app/components/user-profile/component.js`
-* `app/components/user-profile/template.hbs`
-* `tests/integration/components/user-profile-test.js`
-
-This co-located `component.js` and `template.hbs` layout actually already
-works in Ember apps today, so the only change required is to update the
-default component blueprint. We will also provide a codemod that can
-automatically re-organize your component files to follow this structure.
-
-### Angle Brackets with Nested Components
-
-Because Octane apps will continue with today's file system layout, we also
-wanted to address the largest blocker to `<AngleBracket />` syntax adoption
-today: components nested inside other directories.
+Because Octane apps will continue with today's file system layout, we want to
+address the largest barrier to `<AngleBracket />` adoption today: components
+nested inside other directories.
 
 For example, if you have a component located at
 `app/components/icons/download-icon.js` (i.e., nested inside an `icons`
@@ -71,8 +44,8 @@ bracket syntax like this:
 <Icons::DownloadIcon />
 ```
 
-Because both of these changes are quite small, they can be implemented
-quickly without requiring us to delay the Ember Octane release.
+Because this is a small change, it can be implemented quickly without
+requiring us to delay the Ember Octane release.
 
 ## Status of Module Unification
 
@@ -92,14 +65,16 @@ Let's call the file system layout that Ember apps use today the "classic"
 layout. While this structure has served us well, it also has several
 shortcomings.
 
-As mentioned above, related files (like a component and its template) being
-separated from each other can be frustrating. While we are planning to
-address this in Octane for components, there are other kinds of files that
-you might want to group together also. For example, you may want an Ember
-Data model and its serializer to be co-located in the same directory.
+In the classic layout, files are grouped by type, not by name. Sometimes,
+this means that closely related files (like a component and its template) are
+separated from each other, and navigating between them can be frustrating.
+
+Ideally, related files would be close to each other in the file system. For
+example, you may want an Ember Data model and its associated serializer to be
+co-located in the same directory.
 
 Early on, Ember CLI implemented an experimental "pods" layout that grouped
-files by name rather than by kind. So, for example, a `User` model and its
+files by name rather than by kind. For example, a `User` model and its
 serializer would be grouped together in `app/user/`, as `model.js` and
 `serializer.js` respectively.