Why make your own input?

In Ember Octane, there's a heavy emphasis on data down, actions up for interacting with the DOM. However, the built-in <Input /> component follows the old two-way-bindings pattern. This is a fine and ok thing to do; I still use Input in all my apps! I really like two-way-binding for inputs! However, it can be a bit counterintuitive to do things like form validation in the Octane style, when you are still using the built-in Input.

Another reason to make your own input is for accessibility reasons. Unfortunately, every popular front-end framework has its share of accessibility problems. Although Ember is doing better than other frameworks in some regards, there are still some things to work through. If you make your own input component, you can programatically enforce that whenever a developer on your team uses it, they pass in some label text.

Lastly, Input has some confusing and inconsistent behavior, since it has to be backwards-compatible. It's in need of a rewrite, but that can't happen without introducing breaking changes into the framework. So, for now, we're stuck with it, at least until someone writes an RFC, gets it accepted, and does the work.

Native input basics

To understand Ember's <Input />, it helps to understand what a normal, native input can do, and what it needs in order to work well for all users. This information will be important to know when we build our own input.

1. inputs and labels are inseparable pals.

Whenever you create an input, it ought to have an associated label. There are two common styles for this:

<!-- put the input inside the label -->
<label>
  First Name
  <input type="text" />
</label>

<!-- reference the label by its id-->
<label for="input-first-name">
  First Name
</label>
<input id="input-first-name" type="text" />

In the second example, you have to be very careful to not re-use the ID assigned to the inputs and labels.

2. inputs have many different possible attributes

A native input can have many different attributes, such as required,aria-labelled-by, id, class, type, disabled, and more. See the input docs on MDN for the full list.

3. inputs have automatic accessibility behavior

Whenever you use the label and input elements, you get some excellent features automatically. They include keyboard navigation, screen reader support, and more. For this reason, you should always use the input element for inputs, not write a weird div that kinda acts like an input.

4. Interacting with the input fires events

Every input has events that fire whenever someone types in it. For example, there is an oninput event as well as onchange. Whenever you tie directly into events, it's important to check your browser compatibility needs. For example, oninput isn't supported in IE9.

5. Follow semantic HTML to avoid UX traps

If you find it difficult to write valid markup and styling for an input, that's a red flag that your designs might have accessibility problems. This pain can save you from making big mistakes. For example, many developers work from designs where the label is hidden and placeholder text communicates the "label." This was popularized by Material Design, and it had some serious UX problems for all users. The MDN docs go as far as to say that you should not use placeholders at all, if you can avoid them.

Writing vanilla JavaScript inputs

In Ember, you can't use things like script tags in the templates, but it's still good to see how one would do this in a vanilla HTML and HTML + JavaScript settings. MDN has a good tutorial on this topic. HTML only

A regular input can send data without any JavaScript at all if it is part of a form:

<form action="/api/names" method="post"> 
  <label for="name">Name:</label>
  <input type="text" id="name" name="user_name" />
  <button type="submit">Send your message</button>
</form>

Clicking "submit" in the example above would send the name to the /api/names endpoint. So, if your app was hosted on https://my-forms.example.com, it would send a request to https://my-forms.example.com/api/names.

HTML + JavaScript

You can write event listeners in JavaScript that respond to user interactions, and attach them to specific inputs.

For example, this HTML and JavaScript code will print the current value of the input to the console:

<label for="name">Name:</label>
<input type="text" id="name" name="user_name" />
<script>
  let myInput = document.querySelector('#name')
  myInput.addEventListener('input', function(e) {
    console.log(e.target.value)
  })
</script>

You can even call an anonymous or specific function from the HTML, although this is considered bad practice for maintainability, testing, linting, etc in many codebases:

<input type="text" oninput="(function () {console.log('ew, gross') })()" />
<input type="text" oninput="someOtherFunction()" />

Using Ember's built-in Input and two-way binding

Now let's take a look at what Ember's own built-in <Input /> does. The Input component, with a capital I, gives you some additional features and shortcuts compared to using a regular old input with a lowercase i. Most importantly, the input's value (what someone has typed into the box) can be "bound" to a property of the component. When the value changes as a user interacts, so does a property available to the JavaScript side. This is called "two way binding" and it's a very common pattern in pre-Octane Ember apps.

In our template, we can use the Input component and set its attributes. Don't forget to include a label! This example is for Ember 3.15+. Note that if you copy-paste this, you'll get errors until you also copy-paste the JavaScript.

<label for="name">
  Name
</label>
<Input type="text" id="name" value={{this.username}} />
<button {{on "click" this.submitName}}>
  Submit
</button>

Now, in the JavaScript file for this component, we can indicate that username should be tracked for changes, and write an action for the Submit button. Just like in the vanilla HTML + JavaScript example, we'll print the input value to the console when someone clicks submit:

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
export default class MyInputComponent extends Component {
  @tracked username = '';
  @action
  submitName() {
    console.log(this.username)
  }
}

Components are often meant to be reusable throughout an app, and it would be bad if we reused a component with hard-coded IDs. You might end up with multiple reused, non-unique ids on the page, which breaks your app. So, we can add in guidFor to generate a unique ID for our component to use. We'll save the results of guidFor to a new property called uniqueId, and use it in the markup:

<label for="name-{{this.uniqueId}}">
  Name
</label>
<Input type="text" id="name-{{this.uniqueId}}" value={{this.username}} />
<button {{on "click" this.submitName}}>
  Submit
</button>

Component JavaScript that generates the unique ID:

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
import { guidFor } from '@ember/object/internals';
export default class MyInputComponent extends Component {
 uniqueId = guidFor(this);
 @tracked username = '';
 @action
  submitName() {
    console.log(this.username)
  }
}

Making our own text input with a lowercase i, level one

Ok, so now you know the basics of how to interact with an input with a lowercase i using HTML and JavaScript, and also how to use Ember's Input with an uppercase I with two-way binding. Now it's time to make our own implementation that does not have two-way binding. This is a toy example, and in the following section, we'll add more features that help ensure that whenever it is used, it is accessible. Let's start with the markup we had before, but make it a lowercase i and remove the value binding:

<label for="name-{{this.uniqueId}}">
  Name
</label>
<input type="text" id="name-{{this.uniqueId}}" />
<button {{on "click" this.submitName}}>
  Submit
</button>

We have a few different paths that we could take, but let's start with the simplest. Ember provides the {{on}} helper for attaching JavaScript behavior to DOM events. Let's watch for the input event to fire, and write an action handleInput to call when it happens. Like before, you will need to copy-paste both the template and the JavaScript before it will work:

<label for="name-{{this.uniqueId}}">
  Name
</label>
<input type="text" id="name-{{this.uniqueId}}" {{on "input" this.handleInput}} />
<button {{on "click" this.submitName}}>
  Submit
</button>

The component JavaScript, which will print the input's value to the console:

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
import { guidFor } from '@ember/object/internals';
export default class MyInputComponent extends Component {
 uniqueId = guidFor(this);
 @tracked username = '';

 @action
 handleInput(e) {
   console.log(e.data)
 }
 @action
  submitName() {
    console.log(this.username)
  }
}

Notice that our handleInput receives an argument, which I named e in the example above. e is short for "event." I could have called it "bananas" if I wanted to instead. Anyway, whenever you use {{on}} to call a component's action, it always passes the event itself as the first argument. Our event is input. If we console.log e, we'd see a huge object for InputEvent. The InputEvent has a property called data that contains the value someone typed into the input!

Now that we have that input entry, we could do things like run validation and display helper text, set a property on this component, or call an action passed into the component from a parent. "Validation" in this context means something like checking to see if a user entry has the right format, and displaying a message to help them edit their information. For example, maybe the input has a character limit, and you want to let the user know that they are over it, and they need to do some editing before submitting.

Making our own text input with a lowercase i, level two

In the previous section, we made a toy example. Now it's time to get to the real challenge - writing an input that requires you to have a label, and handles its ids gracefully and automatically.

I don't have a one-size-fits-all implementation for you (yet). However, my apps really only had three different flavors of inputs anyway - a basic text input, a text input with labels hidden because I had no choice in the design, and then non-text inputs whose attributes varied wildly. It's up to me to figure out which kind of input is used the most, and design an easily reusable component for that use case first. This would have the greatest impact in the shortest amount of time. Then, I should work through all the other cases throughout my app.

First, let's make our text input more generic, and have it rely on properties that are passed in. I'll explain the rationale for each one in a moment:

<label for="input-{{this.uniqueId}}" class={{@labelClass}}>
  {{@labelText}}
</label>
<input type="text" id="input-{{this.uniqueId}}" class={{@inputClass}} {{on "input" @handleInput}} value={{@initialValue}} />

Next, let's define the JavaScript that provides the uniqueId and enforces that @labelText is passed in:

import Component from '@glimmer/component';
import { action } from '@ember/object';
import { tracked } from '@glimmer/tracking';
import { guidFor } from '@ember/object/internals';
export default class MyInputComponent extends Component {
 uniqueId = guidFor(this);

 constructor() {
   super(...arguments);
   if (!this.args.labelText) {
    assert('All inputs must have labels! MyInputComponent requires passing in labelText, i.e. <MyInputComponent @labelText="First Name" />')
  }
 }
}

Here's my rationale for each attribute passed in, or not passed in:

labelText: I will want to customize the label displayed every time I show this input labelClass and inputClass: My input and its label need to look different depending on their context in my app.

initialValue: I commonly need to pre-fill the input with the data that's available. For example, I might already know the username from when someone logged in. I call it initialValue to help prevent a developer from thinking that it is two-way-bound.

handleInput: following data down, actions up, we should call a method passed in from the parent in order to modify data.

id: I did not make id a property to pass in, because it's best practice to not use ids in CSS. type: I also did not pass in type, since I prefer having components that are easy to understand and use, instead of a component that is complicated but ultra-reusable. I try to ask myself whether the component I'm making would need to be explained to a new hire, or if it would be self-explanatory.

Sidenote: I could have also used an Input with a capital I in my template example above, and written it to use two-way binding. I might go that route if I am refactoring an app that already makes use of two-way-bound inputs.

Making this happen for everyone

Do you think that this sort of thing should be part of Ember's out-of-the-box toolset? The best solutions are those where you don't need to understand a lot in order to do the correct thing! There is a group of developers working to improve Ember's accessibility right now, and they are working through this issue to problem solve and fix outstanding problems. If you would like to participate, speak up in the #st-a11y channel in the Ember Community Discord.

Another approach to handling DOM events

Ember Octane popularized the use of modifiers, which provide a way to attach events or behavior as an element renders. There are some examples of modifiers in the ember-modifier library's README. One could write a modifier that attaches and tears down event listeners for an input. This could be helpful if you need something that is both really fancy and reusable.

Yet another way to handle events

Ember contributor and core team member Chris Garret has written an addon that provides a helper called box. This addon isn't part of Ember itself, and you would have to install it yourself in order to use it.

The {{box}} helper provides a way to add two-way-binding-like behavior to templates in a way that is concise and element-agnostic.Even if you don't plan to use box, it may be helpful to read it over as a way to boost your own understanding of the types of abstractions that people could create for handling DOM interactions.

In conclusion…

It's worth stating here that there's nothing wrong with using Input in your app, but there is something wrong with not using labels and aria attributes appropriately. It is up to you and your team whether you choose to enforce correct HTML through programmatic means, or just try to catch it in peer reviews.

I strongly recommend going the programmatic route whenever you can. This allows your fellow developers to learn on your own, and prevents the case where one developer is exhausted by enforcing standards while their colleagues grow annoyed. I have been on both sides of that table. I really prefer when the code helps me fix my own mistakes.

Good luck!

It's a lot to take in, especially when you're used to Ember always looking the same year after year, but I think you'll enjoy the results. We don't have enough time to get into why these things exist, but if you have questions, ask away.

If you are new to Ember, check out this article instead.

Impact on existing apps

Nobody panic. Octane's features are done through minor releases.

Existing apps can keep doing their regular upgrade cycle, as they did before. Although Octane looks like lots of changes to Ember, they are provided as opt-in, non-breaking features. You would only see differences if you generated a new app, which has the Octane features all enabled.

Upgrading existing apps

If you want an existing app to be "Octanified," you will need to change some configuration settings in your app, to do things like disable JQuery and enable Native Class Components as the default. From there, you'll be able to gradually change your app's syntax, wherever you feel like doing so. For the most part, you can use a blend of features. Classic and Native Class Components can coexist.

What will be different in freshly generated apps

While playing around with the Octane preview/pre-release, here are the five areas where I needed to sit down and really learn them, not just copy/paste:

1. Native Classes
2. Decorators
3. Using @tracked instead of Computed Properties
4. Element modifiers instead of component lifecycle hooks
5. Enforced data down, actions up

An app created with ember new after Octane is released will be using all these features above, and more.

Native classes

Whenever you import Component from @glimmer/component instead of @ember/component, you'll be in Native Class land. Classes are now a feature of JavaScript. If you find Class syntax confusing, it may be helpful to experiment with them some outside of Ember. This way, you'll have a clear picture of what is Ember and what is regular JavaScript.

Please note, you don't have to go learn Glimmer, even though the import comes from there.

Here's what a Component looks like using the new form:

import Component from '@glimmer/component';
import { action } from '@ember/object';

export default class HelloButton extends Component {
  text = 'Hello, world!';

  @action
  sayHello() {
    console.log('Hello, world!');
  }
}

Pretty weird, huh? No commas. No nesting inside an action object. Now actions are done using Decorators.

Components, Routes, Controllers, Services, Ember Data Models, etc. will all be available as Native Class imports.

Decorators

Decorators start with an @. They are already popular in tools like Angular and TypeScript, and are a Stage 2 JavaScript language feature. You can read about the general concept here. If you create a Native Class version of a Component, Service, Controller, etc., then you can use decorators inside it.

The most important decorators to know about and use are @action and @tracked. Actions work more or less the same as they did before. @tracked is something new, and you'll use it instead of Computed Properties. Keep reading for more information on that. You can also make your own Decorators if you're feeling fancy.

Using @tracked instead of Computed Properties

Just to be clear, Computed Properties aren't gone from Ember. You can keep using them in "Classic" (aka non-Native Class) Components, Controllers, Routes etc. in your app. But if you are switching to Native Classes, you have two options for refactoring your computed properties.

As a first pass, you could use the @computed decorator inside your Native Class thing:

import { computed } from '@ember/object';
// ...
  @computed('firstName', 'lastName')
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
// ...

But really what you want to use is @tracked. You decorate (or label) the properties that you want to be watched for changes:

import { tracked } from '@glimmer/tracking';
//...
  @tracked firstName;
  @tracked lastName;

  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
// ...

I can use {{this.fullName}} in my template, just like before.

Element Modifiers instead of lifecycle hooks

Ember Components have lifecycle hooks like didInsertElement that are popular places for shenanigans like inserting charts, registering features from non-Ember UI libraries, etc.

In Native Class Components, instead of declaring a didInsertElement method in your JavaScript file, you tell the template which action to run when the element renders:

<div {{did-insert this.someAction}}>
  ...
</div>

When that div renders, the action someAction will be called automatically. Pretty neat! As someone who used that hook a lot when using data vis tools like D3, I love this.

Enforced Data Down, Actions Up

In "classic" components, if you pass a property from a parent component to a child component, the child component could make changes to it, and those changes would affect every other place that same property was used. The change would show up in the parent, in other components, etc. This was referred to as "two way binding."

Now, for Native Class components, two way binding is no more.

If a child component tries to set a value of a property, it can only set the value on itself. The property from the parent is unchanged.

To give an example, let's say we have a property penguins passed from a parent component into a child component, and its value is zero.

<ChildComponent @penguins={{this.penguins}} />

In the child component, we try to set the value of penguins to 5, by calling this action:

@action
morePenguins() {
  this.penguins = 5
}

In the child component, here's what we get displayed:

{{@penguins}} <!-- 0 - this is the property from the parent -->
{{this.penguins}} <!-- 5 - this is the component's own property -->

In the parent component, the value of penguins is still zero too.

To change the value of penguins on the parent, we'd have to pass down an action that the child component can use:

<ChildComponent @penguins={{this.penguins}} @someAction ={{this.evenMorePenguins}} />

Learn more

The goal of this article was to cover what to expect, in very brief terms. Ready for more?

• Learn what editions are here
• Octane-specific official resources are here, including how to test out the preview/pre-release
• There are excellent, in-depth resources written mainly by Chris Garret, both for the Guides and a personal blog.
• Ask questions in the Community Chat

Good luck learning!

"May I ask a Question" is a month-long effort that includes livestreams and an invitation for community participation. Chris and I find an Ember-related Stack Overflow question and share approaches to building and debugging, while making a minimal reproduction of the problem and delivering an answer. Our goal is to help make Ember more approachable for beginners and to demonstrate a Q&A style that is centered in curiosity and exploration. We'd love you to help with these things too!

Although we are both members of Ember core teams, this is a side quest for us and is not affiliated with official projects or the organization.

The many sides of Stack Overflow

Last year, when we set out to encourage more participation, we got to see firsthand both the positive and negative sides of Stack Overflow. The Ember section was very chill and seemed great to us, but outside of that zone, there were problems. We got to see how the people behind the project think about the problems that we and many other users encountered. We feel good about continuing this project since there seems to be thoughtfulness and progress.

On the sunny side, we are so inspired by the people who have been consistently doing Ember Q&A over the past year!

The livestream

Our first livestream of 2019 is Wednesday, May 1st at noon UTC/8am EST!

In general, we're livestreaming on Thursdays or Fridays at noon UTC/8am EST. Recordings will be posted after each session.

For announcements of when we are streaming: 

• follow us Twitter (jwwweber and real_ate)
• follow (Chris on Twitch)(https://www.twitch.tv/real_ate)
• Watch our recordings on YouTube

How you can participate

We would love it if more people want to jump in and help answer questions, or upvote the good work of others! The most important thing I can stress is this - figure out what you enjoy, maybe bring along a friend who likes it too, and do that thing. If Stack Overflow sounds overwhelming, maybe it's not your jam, and that's ok. There are so many different, critical ways to support an open source project. It's totally fine (and healthy!) to ignore certain aspects. It's really important to not burn yourself out on trying to pay attention all the time. If you want to give Stack Overflow a shot, here are some tips:

• Upvote good questions and answers. You're giving people who are already engaged a nice boost, and maybe some additional abilities
• Include versioning in your answers. The opening sentence should say something like "This applies to Ember 3.x.x, and was written as of 3.1). Future devs will thank you.
• If you search SO during your daily work and see answers from the past that are now outdated, comment with the modern answer.
• Join the Ember Community Chat if you want some company, spot an issue that should be modified, or can help with higher level operations like vote to close, editing, etc.
• Use code snippets whenever possible
• Help improve the quality of questions - if someone hasn't provided enough information, comment and ask for more. This will help you, them, and anyone else who lands on the question from Google!
• Link back to the Docs or the Guides or both
• Be excellent to each other. Every comment you make should be kind, helpful, and true.
• If you want to receive email alerts when someone responds to your questions and answers, check out your Profile settings
• Invite people to share their questions in the Discuss forum or on Stack Overflow in order to help make them searchable Abandon ship if you don't like it. Your energy is needed elsewhere.

Thanks for reading!

If you have any ideas for us, you can reach us both on the Ember Community Chat!

About us

Jen and Chris are both volunteer members of the Ember.js learning core team, where they build, write, and maintain public-facing resources for the framework.

Chris Manson is a developer at simplabs. He's the creator of Authmaker and Empress, and is an mentor and Ember.js advocate.

Jen Weber is an engineer at Cardstack. She is an active open source developer, tech writer, and public speaker. She works to make tech a more welcoming industry.

The symptoms

Today, I was working on fixing the following Ember Data deprecation:

DEPRECATION: Attempted to call store.serializerFor(), but the store instance has already been destroyed. [deprecation id: ember-data:method-calls-on-destroyed-store]

Everywhere I could, I put checks like this.store.isDestroyed so that I could find and skip the offending code, but that didn't help. It always turned out to be false, and therefore useless to my debugging.

I thought, maybe this is some weird Ember Data thing, and I should look into that more.

Spoilers - it wasn't a weird Ember Data thing.

I asked for help on the Ember Community chat, and Chris Thoburn aka Runspired helped me out. I almost always leave conversations with him by thinking, I need to write a blog post about that.

The problem

Here's what was going on.

My acceptance test was leaking state, meaning that some asychronous code was resolving after the test had already moved on and reset some resources for the next test. This process of bringing the test back to a "clean slate" is referred to as "test teardown" in Ember and other JavaScript environments.

In my case, an afterEach hook that destroyed the store was happening before the code was actually done. However, you might see the same sort of thing if you use this.anything after the testing teardown steps.

Finding the cause

The test itself was fairly normal, and used Ember's async test helpers just like it was supposed to:

test('track field dirtiness in owned, related records', async function(assert) {
  await visit('/hub/posts/1');

  let reviewStatusActionTrigger = findTriggerElementWithLabel.call(this, /Comment #1: Karma/);
  await click(reviewStatusActionTrigger);

  let karmaInput = findInputWithValue.call(this, '10');
  await fillIn(karmaInput, '9');
  assert.dom('[data-test-cs-version-control-button-save="false"]').exists('Save button is enabled');
  assert.dom('[data-test-cs-version-control-button-cancel="false"]').exists('Cancel button is enabled');
});

The test code was doing what it should. Chris confirmed that it was my app code causing the problem, not an Ember Data issue, nor this test. But where could it be hiding?

My first strategy was that I commented out parts of the test until I figured out exactly which interaction caused the problem. Something happened after doing the fillIn.

I followed the code to see what actions were active. It turns out that the component was using a Service to do fetch data, and then using the Ember Data serializer to parse the response:

async validate(model) {
  let responses = this.toValidate.map(async (record) => {
    let { url, verb } = this._validationRequestParams(record);
    let response = await fetch(url, {
      method: verb,
      headers: this._headers(),
      body: JSON.stringify(record.serialize())
    });
  });

  let json = await Promise.all(responses);
  // do more work
}

The offending line was record.serialize(), which needs Ember Data, and my tests weren't waiting for the result.

Fixing it

I could think of three possible paths forward:

• Stub the service
• Make the tests wait (how???)
• Check the Ember environment in my app code (ew)

Stubbing the service was easiest in this case. When you "stub" a service, you make a fake service that the test uses.

The actual code for the service used by the component was over 200 lines, but the component was only using three functions from it!

There are just a few steps to stubbing a service:

1. Move this troublesome test into its own file.

My acceptance test had many smaller tests within it, but only one had async problems. I didn't want to have to stub every service function used by every one of those tests, so I moved the deprecation-triggering test into its own file.

I can run this test alone with ember test --server --module "Acceptance | your test name". The module is whatever is specified in the test: module('Acceptance | your test name', function(hooks) {...}).

Alternately, to run my test alone, I can use ember test --server --filter "some term" where some term is found in the line test('here is some term', async function(assert) {...}

The --server means that my tests will automatically re-run when I make changes, and it runs much much faster than doing ember test repeatedly by hand.

2. Create the stub in the acceptance test.

Next I made my fake service. I looked at the component to see which functions it used. I studied those functions to see what kind of data they should return, and console logged the things they returned when the test was runnning. The asynchronous methods return a promise, and the other methods return data that the test needs to render.

The example below is Ember 3, but if you're using an older version of Ember, this other article might help you out with service stubbing. Ignore the pop-ups. There's no paywall.

// my stubbed service

let StubCardstackDataService = Service.extend({
  validate() {
    return Promise.resolve({})
  },
  getCardMeta() {
    return 'Comment #1'
  },
  branches() {
    return []
  },
  fetchPermissionsFor() {
    return Promise.resolve({mayUpdateResource: false, writableFields: ['karmaValue', 'karmaType']})
  }
})

4. Inject the test in the beforeEach hook.

This special function runs before every test. Instead of using my real cardstack-data service, the component will use my fake service when it runs the test. In order to make that happen, I have to register my service.

hooks.beforeEach(function() {
  this.owner.register('service:cardstack-data', StubCardstackDataService);
});

Make sure the information that you give to register() matches the name of the service used in the Component.

The final result

If you want to see how the stub is used in the context of the whole test, check out resulting PR here!

Takeaways

One thing I learned from this experience was that if I am writing components that have async data fetching behavior, there's a huge benefit to putting that code into a Service. That way, I can stub it easily in my tests!

This isn't the only way to handle this problem - remember, I outlined 3 options earlier, and there are probably more.

My other takeaways are that whenever I can, I should lean on Ember Data and the model hook to do data requests. Sticking closely to the "happy path" in Ember means that you get some async data handling for free. I was working on a project that does not have model hooks because it has no route files (weird, right?), but a normal Ember app has more async-handling features available!

For more information

Here are some resources that I found helpful while learning and debugging. Thanks to these authors for their great work!

• The offical Ember tutorial's example of stubbing a service
• Ember Timer Leaks by Evan Farina
• Testing your Ember application in 2018 by Scott Newcomer. Ok so it's not 2018 but if the async/await in this article is news to you, this is a really great primer
• Similar to the item above, The future of Ember Testing presented by Tobias Bieniek

Thanks!

Thanks for reading and especially thanks to Chris Thoburn for the help!

About the author

Jen Weber is web developer and writer based in Boston, USA (she/her or they/them). As a member of the Ember Core Team, she works on code, docs, and contributor engagement for the Ember.js front end framework. Jen works at Cardstack, where she helps build tools to power Web 3.0. She is a fan of open source and making tech a more welcoming, inclusive industry.

Rebasing is commonly a nightmare for newer devs or even experienced devs who don't use this workflow often, but it doesn't have to be! Here's how I walk people through their first squash and rebase. There are a ton of excellent articles and videos on this, but everyone does it a little differently. I like this video by The Modern Coder that shows part of the process in action. After a few times doing this process, it will feel tedious but straightforward. No nightmares here.

Set your default text editor in git

You only need to do this once. Skip this if you already configured this on your computer. If you have not set your default editor for git, then some of the steps below would open in vim, which is difficult to use if you have zero practice with it.

I use VSCode, and so I used the one-line command in this article by Carl Saunders.

Steps to squash and rebase

Create a backup branch and push it up to GitHub/Gitlab/etc. This backup branch will have all your work nice and safe in case you need to start over.

git checkout my-branch-name
git branch backup-my-branch-name
git push origin backup-my-branch-name

Look up the commit id of the most recent commit that isn't yours, and copy it:

git log

Start the rebase, replacing the placeholder text below with the commit id you copied:

git rebase -i the-commit-id-you-looked-up-goes-here

Mark the commits you want to squash by putting "s" instead of "pick" in front of all the commits except the first one. The one at the top should still say "pick." If there are a ton of conflicts, sometimes it's best to do some pair programming with the other dev(s) who made changes to these files. They can help you decide what to do.

Save and close, and wait for a new text editor prompt to pop up.

Enter your commit message.

Save and close.

Squashing should be complete. Check for any problems:

git status

Next, I'm getting ready to rebase. All my collaborators merge their work into a branch called main, so that's what I'm using in this example. I pull that branch first, just to make sure my local copy is up to date:

git checkout main
git pull origin main

Time to actually rebase. Check out your branch, and rebase!

git checkout my-branch-name
git rebase main

Fix any git conflicts just like you would if you were merging something.

Stage the files once you have resolved conflicts:

git add some-file.js another-file.html example.txt

Then, finish the rebase:

git rebase --contine

You overwrote git history, so you will need to force push your work up. Make sure you are on your own branch before running this! It will overwrite other people's work if you are on the wrong branch.

git push --force-with-lease origin my-branch-name

If something goes wrong

No worries, you have a backup branch! Ask a colleague for help. This is a learning opportuinity. If you are all alone and you don't have anything else at all to work on, you could try the following to put things back to how they were. Be careful, don't lose your work!

Abort the rebase in progress:

git rebase --abort

Rename the messed up branch:

git branch -m messed-up-my-branch-name

Check out your backup branch. You may need to discard changes/new files with git restore before this command can be run.

git checkout backup-my-branch-name

Copy your backup, and give the copy the name you were using before:

git checkout -b my-branch-name

Now you are back to where you started, and can try again.

Why squash before rebase?

Whenever you rebase, git compares every commit to the rebase target to see if there are conflicts. It makes you resolve them before you move on. Sometimes, this is useful - maybe you want to step through. But most of the time, fixing the conflict causes even more conflicts.

Instead, we want to squash all our work into just one commit. Then we resolve any conflicts just once, and then we are off to the races.

When should I not squash before rebase?

Every company/project has different norms about how they like to manage their project git history. If they tell you not to squash or rebase, then don't. Ask to pair program with someone a few times to get a sense of a nice workflow for their process.

This is Part 4 of a series of blog posts. We're on a journey together to remodel an older Ember app, ember-api-docs, incrementally bringing it up to date with the latest and best Ember and Ember Data patterns.

For this series, I'm pair programming with Chris Thoburn, aka @runspired, who is known for his work on Ember Data. He has over 500 commits and some great debugging skills that you and I can learn from.

What you will learn in this segment

• How to find codemods
• How to run the codemods
• How to decide what to change, and what to leave alone
• Where jQuery fits into the story

The road so far

So far, we have upgraded our dependencies and tests are all passing. This sets a strong foundation for running codemods and then making sure that tests keep passing.

Octanify

Ember Octane is Ember's first "edition." You can think of an edition as a collection of features and syntax that together form a cohesive mental model. There are multiple ways to accomplish a feature in Ember, and Octaneified apps use the latest styles.

There is a CLI command that configures an app to use Octane:

npx @ember/octanify from   which set some dependencies and flipped flags in optional-features.json

You can find more instructions about this command in the Ember upgrade guide. In short, it sets some dependencies in package.json and feature flags in optional-features.json. Optional features are one way that new features are rolled out in Ember apps without making breaking changes. When you are ready, you can opt into them, but if you are not ready, you aren't blocked from upgrading. Regular upgrading is critical for companies and teams that value getting security, bugfixes, and feature updates over long periods of time.

Octanify sets the following feature flags in optional-features.json:

{
  "default-async-observers": true,
  "jquery-integration": false,
  "template-only-glimmer-components": true,
  "application-template-wrapper": false,
}

You can learn all about these individual features in the Optional Features Guide.

Handling jQuery

For our app, all the optional features set by Octanify were fine. Setting jquery-integration: false meant that instead of using this.$() in our apps, we had to install @ember/jquery and import jQuery individually - no problem. However, the jquery-integration flag made us wonder, could we remove jQuery from our app altogether? We were only using it in one place in our app, and doing so would cut some kb from our app.

However, we didn't just need to check our app. We also had to check if any addons used jQuery. I used to search my node_modules for usages, but that would return a lot of false positives compared to a strategy that Chris Thoburn showed me.

Chris first ran the build for the app:

npx ember build

By default, the command puts built files in the dist/ directory. Then, Chris was able to search for this.$ and Ember.$ and confirm that our app's addons did not need jQuery. This is better than searching node_modules, since we are only checking for the use of jQuery in addon features we are actually using.

Another common use of jQuery in apps is via Ember Data. By default, Ember Data uses jQuery for its HTTP requests. However, if an app has ember-fetch installed, it will use fetch instead. It's important to install ember-fetch in order to provide broad browser support for your fetch requests.

Finally, we took another look at our direct use of jQuery in this app, in our Table of Contents component:

import { action } from '@ember/object';
import Component from '@ember/component';
import jQuery from 'jquery';

export default class TableOfContents extends Component {
  @action
  toggle(type) {
    jQuery(this.element)
      .find('ol.toc-level-1.' + type)
      .slideToggle(200);
  }
}

jQuery is providing a nice open/close animation for one of our menus. Whenever I see jQuery in use, I always check youmightnotneedjquery to see if there's an easy alternative. In this case, there was not, so in the interest of moving forward, we leave jQuery in our app for now, and open an issue asking for help making a new CSS/plain JavaScript animation.

It's not a huge deal to leave jQuery in your app unless you have a strategic, benchmarked focus on app performance. jQuery is an incredibly successful project - so successful that its best features are now provided by native browser JavaScript. Ember's API documentation app is used by developers around the world with varying internet quality levels, and so we do need to save some kb where we can, however this one task should not block our progress towards improving other areas of the app.

Ember CLI Update Codemods

Now on to some more codemods. Ember CLI Update can update your dependencies, and also provides a subset of the most common codemods that make deeper changes.

After running dependency updates, you can run the codemods like this:

# Start your app
npx ember serve
# Run the codemods
npx ember-cli-update --run-codemods

Some codemods start with the letters fpe. This stands for "function prototype extension."

Additional codemods

There are many more codemods than those provided by Ember CLI update. One good place to look for them is ember-codemods on GitHub.

Some codemods require that you have your app running. That's why we start the app with ember serve. Such codemods look at the built files in order to infer the correct changes to make. This is possible through a strategy called telemetry, via ember-codemods-telemetry-helpers.

A problem with one codemod

When we ran ember-modules-codemod, we encountered an error. The codemod helpfully told us which line it failed on:

titleToken(model) {
  return model?.fn?.name;
}

This line of code uses optional chaining, with ?. syntax. Optional chaining is a feature of JavaScript that was added after these codemods were initially written.

We can see for ourselves one of the challenges of codemods - when they are written, they are a snapshot in time. It takes work to keep them functioning as JavaScript and Ember apps change. If you are working on a large app, it may be less work to fix a codemod bug than to make all the changes by hand. Additionally, codemods are written to work for individuals' apps, and so it takes community effort for codemods to work across many edge cases that authors could not forsee.

Another example of maintainability issues with codemods is the ES5 getter codemod - you have to run it before you run native classes codemods, because it doesn't know how to parse native classes. They didn't exist when the getter codemod was written. These aren't unsolvable problems, but they mean that developers whose apps are super out of date may have a harder time upgrading. There are many benefits to having a regular ugrade and maintenance schedule for your work, and this is one example.

Configuring VSCode to play nice with decorators

Some of the codemods we ran introduced decorators. VSCode was our code editor of choice, and its default linters didn't like the use of decorators.

We removed jsconfig.json from our app's .gitignore, and then configured VSCode to stop yelling about decorators in jsconfig.json:

{
    "compilerOptions": {
      "experimentalDecorators": true
    },
}

Dealing with codemod mistakes

Not all codemods are flawless. There's a lot of variation in an app! You should think of them has helpful suggestions, rather than a complete solution to your upgrade process. The best way to catch codemod mistakes is to carefully review the diff, run your tests, and make a commit after each codemod. Here's an example issue we had with a codemod that rewrote link-to:

// before codemod

{{#link-to
  data-test-uses-link
  (concat parentName section.routeSuffix)
    model.project.id
    model.projectVersion.compactVersion
    model.name
    item.name
    (query-params anchor=item.name)}}
  {{item.name}}
{{/link-to}}

// after codemod
<LinkTo @route={{concat this.parentName section.routeSuffix }} @models={{array this.model.project.id this.model.projectVersion.compactVersion}} @query={{hash anchor=item.name}}>

The codemod cut out some of our route segments, leading to incorrect links in one part of the app:

// correct
/ember-data/3.26/classes/Ember.Inflector/methods/singular?anchor=singular

// incorrect
/ember-data/3.26/classes/ember-data/methods/3.26?anchor=singular

How did this happen? We took a look at the source code for the codemod, and saw that it has special handling for dynamic routes, query params, and data-test. When we used all three of these things together in one link-to, it was the perfect storm.

Codemod strategies and takeaways

Our upgrade would have been easier if we ran a single codemod at a time, and make it its own commit, and ran it in CI, and shipped it. If you have the ability to roll your app back quickly in production, you don't need to work as carefully.

That said, you really need to go through the diff if you try to do a big bang upgrade.

If your test suite coverage is bad, and you can't improve it, you can run codemods on specific chunks of code and QA them - do one set of related components at a time, then look at the diff and click test. Many (or maybe all) codemods accept file paths in the CLI commands.

Conclusion

That's it for codemods! Next up, we will take a look at the code that couldn't be modded, and do some refactors to simplify the app now that we have Octane's awesome features available, such as tracked. Thanks for reading!

We will walk through updating a complex, real-world app, ember-api-docs, which is the front end of api.emberjs.com. Along the way, you will learn how to approach this process for your own apps - updating dependencies, debugging build errors, migrating to Octane syntax, writing better Ember Data serializers & adapters… there's a lot to do!

For this series, I'm pair programming with Chris Thoburn, aka @runspired, who is known for his work on Ember Data. He has over 500 commits and some great debugging skills that you and I can learn from.

Preparation

The focus of this first article will be about deciding where to begin, what kind of mindset to have, and an overview of the debugging tools in our toolbox. There are a lot of things we could work on improving in this app, and there are multiple paths we could take that lead to success.

Areas of focus

Making a list of them and prioritizing is very important step for any app refactor or upgrade. Some broad tasks to consider include:

• Updating to the latest package versions
• Resolving deprecations
• Running codemods
• Refactoring confusing stuff
• Documentation
• Testing and QA

Making a detailed list

Thinking about these areas of focus helps me get started with making a detailed list.

Chris Thoburn and I did a brainstorm about ember-api-docs and came up with the following list:

• Upgrade Ember and Ember data versions
• Run some codemods for Octane
• rewrite computed properties to cached getters, simplifying where possible (reduce intermediary computed properties)
• Figure out how to use less of Ember Data
• Figure out what needs to be in API response meta
• audit models and remove async relationships that didn't need to be async and ensure that inverses were properly wired
• make sure the API returned the format the store expects, and remove the serializer entirely
• Remove the adapter and replace it with one that just does a simple fetch request
• drop both the adapter and the serializer package and the ember-data package, instead installing store and model and record-data directly

Prioritizing

Next up is prioritizing. This can be hard to do when you don't know an app well, and that's ok. This list's ordering should shift over time as you learn new things! But you do need to decide what to try first.

For this app, the clear first step is to upgrade the Ember and Ember Data versions.

We start here so that we have all the latest and greatest features. This can also be a challenging step because shifting dependency versions sometimes reveal bugs, but finding them later in the middle of a refactor is no fun.

Getting in the right mindset

Overhauling an app (or even a complex component) takes a different mindset than I use in my usual daily coding. Most days, I have expectations about how the code works, because I wrote it or studied a section of it closely. But in an overhaul, big upgrade, or refactor, there are a lot of unknowns! If I intentionally adopt a different mindset at the beginning of a big uprade, I'm a happier developer. What's that mindset look like?

When I make a change that does not fix a problem, I try to be curious about why.

When I see a different error, I treat it as a step forward.

I keep a list of my successes as I go, including learning new things or getting one step deeper into the process.

When I get stuck, I conduct small experiments, and record the results.

I accept and expect that some of my experiments will be dead ends.

When I don't know where an error is coming from, I focus on trying to find the source before trying to fix the error.

I am skeptical of the things I changed, by default. This especially includes what's in the node_modules folder and shifting dependency versions.

General debugging strategies

Over the course of this series, we will use lots of different debugging techniques. You will see examples of all of these! But it's useful to look at them as a group, and think of this as tools in your toolbox.

• Selectively commenting things out from your app to hone in on where a problem is coming from. Chris calls this "bisecting," and I call it "Cat in the Hat" debugging. Identifying the areas that are not a problem is progress!
• Cleaning out node_modules - deleting the app's node_modules folder and the lock file, either package-lock.json or yarn.lock, and reistalling dependencies
• Restarting the local server - important to do if you change dependency versions or build configuration
• Logging template values to the console. In your .hbs files, you can add {{log this.myVariable}} and see the output in the console
• If your app is using it, turning fastboot off while you debug. Add ?fastboot=false to the end of your locally served URL, i.e. http://localhost:4200/?fastboot=false.
• Using "Break on exceptions" or "Break on uncaught exceptions" in your browser's debugging tools, to help with finding out where errors are coming from, with some more informative context
• Using debugger in your js files to set breakpoints that you can see in your browser's debugging tools
• Using yarn why package-name or npm ls package-name to confirm which versions of dependencies are actually in use, and which other dependencies use them.

Up next

Next, in Part 2, we will start doing the app version upgrade!

This is Part 2 of a series of blog posts. We're on a journey together to remodel an older Ember app, incrementally bringing it up to date with the latest and best Ember and Ember Data patterns.

About the series

We will walk through updating a complex, real-world app, ember-api-docs, which is the front end of api.emberjs.com. Along the way, you will learn how to approach this process for your own apps - updating dependencies, debugging build errors, migrating to Octane syntax, writing better Ember Data serializers & adapters… there's a lot to do!

For this series, I'm pair programming with Chris Thoburn, aka @runspired, who is known for his work on Ember Data. He has over 500 commits and some great debugging skills that you and I can learn from.

Deciding how to approach upgrading dependencies

There are two main approaches Ember developers take, either:

1. Upgrade addons
2. Upgrade core Ember and Ember Data dependencies

Or, they approach this in the reverse order:

1. Upgrade core Ember and Ember Data dependencies
2. Upgrade addons

The path you choose depends on your app - how many addons does it have? How outdated are they?

In our case, we decided on the latter. We didn't want to introduce too many changes at once if we didn't have to, and we were pretty confident in our ability to sort through addon-specific errors.

Running the Ember and Ember Data upgrade

This app was on 3.16. The latest Ember and Ember Data version is 3.26.

We can do the upgrade with the help of ember-cli-update, which will apply the blueprint used for fresh apps.

npx ember-cli-update

You can read a whole bunch about upgrading in the Ember Guides and Ember CLI Guides, so we won't go into too much detail here.

We reviewed each file that was modified first, to confirm that we wanted those changes.

Then, we walked through all merge conflicts and resolved them.

Next, we installed our new dependencies with yarn install.

Finally, we started the Ember server with npx ember serve and hit our first bug.

(Why npx ember serve? npx ensures that the Ember CLI version used by your app is the one specified in package.json, and not your globally installed version. It usually doesn't matter, but when it does, it's often when working on upgrade tasks like this!)

Debugging a build failure

Here's the build failure we saw in the console after we started up our server:

Build Error (broccoli-persistent-filter:Babel > [Babel: @ember/ordered-set]) in @ember/ordered-set/index.js

Duplicate plugin/preset detected.
If you'd like to use two separate instances of a plugin,
they need separate names, e.g.

  plugins: [
    ['some-plugin', {}],
    ['some-plugin', {}, 'some unique name'],
  ]

Duplicates detected are:
[
  {
    "alias": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js",
    "options": {
      "emberVersion": "3.26.1",
      "root": "/Users/jweber/projects/ember-api-docs",
      "name": "@ember/ordered-set"
    },
    "dirname": "/Users/jweber/projects/ember-api-docs",
    "ownPass": false,
    "file": {
      "request": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js",
      "resolved": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js"
    }
  },
  {
    "alias": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js",
    "options": {
      "emberVersion": "3.26.1",
      "root": "/Users/jweber/projects/ember-api-docs",
      "name": "@ember/ordered-set"
    },
    "dirname": "/Users/jweber/projects/ember-api-docs",
    "ownPass": false,
    "file": {
      "request": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js",
      "resolved": "/Users/jweber/projects/ember-api-docs/node_modules/ember-compatibility-helpers/comparision-plugin.js"
    }
  }
]

Not very nice.

We did yarn why @ember/ordered-set to confirm that only one version of that dependency was in use:

yarn why @ember/ordered-set

yarn why v1.22.10
[1/4] 🤔  Why do we have the module "@ember/ordered-set"...?
[2/4] 🚚  Initialising dependency graph...
[3/4] 🔍  Finding dependency...
[4/4] 🚡  Calculating file sizes...
=> Found "@ember/ordered-set@4.0.0"
info Reasons this module exists
   - "ember-data" depends on it
   - Hoisted from "ember-data#@ember#ordered-set"
   - Hoisted from "ember-data#@ember-data#record-data#@ember#ordered-set"
info Disk size without dependencies: "44KB"
info Disk size with unique dependencies: "1.98MB"
info Disk size with transitive dependencies: "47.57MB"
info Number of shared dependencies: 151
✨  Done in 1.83s.

Chris hypothesized that this was due to floating dependencies. Yarn and NPM let developers specify a range of acceptable dependency versions. Sometimes there are mismatches. It's often a good initial step to try deleting node modules and the lock file, as a small experiment, and then try again:

rm -rf node_modules
rm yarn.lock
yarn install
npx ember s

That resolved the error about duplicate plugins!

On to the next error - dependencies of dependencies

Next, we saw some errors about ember-popper.

We looked to see what was using ember-popper using yarn why. One of our dependencies, ember-styleguide used it. We looked at a more recent version of ember-styleguide, in the package.json. The latest ember-styleguide didn't even use popper, so upgrading ember-styleguide got us over this hurdle.

We also saw an error about ember-basic-dropdown. yarn why told us it was used by ember-power-select. Upgrading ember-power-select and following instructions in the CHANGELOG fixed that issue.

Now, when we did yarn install and npx ember s, the app built successfully.

Debugging runtime errors

Now when we visted localhost:4200, we saw something strange. The app would render for a moment (thanks to Fastboot), but then when the app's JavaScript loaded in fully, it crashed.

Apps that use Fastboot show their errors in the terminal running the server, not the browser console. So, to get a closer look at what was going on, we temporarily turned off fastboot by visiting http://localhost:4200?fastboot=false.

There were two errors in the browser console:

One:

Error occurred:

- While rendering:
  -top-level
    application
      es-header
        es-navbar
          bs-navbar
            bs-navbar/content
              bs-collapse
                bs-navbar/nav
                  search-input
                    ember-tether
                      search-input/dropdown

Two:

Uncaught (in promise) ReferenceError: process is not defined
    <anonymous> Ember
    js vendor.js:173080
    __webpack_require__ vendor.js:172838
    <anonymous> Ember
    js vendor.js:173069
    __webpack_require__ vendor.js:172838
    <anonymous> Ember
    js vendor.js:173126
    __webpack_require__ vendor.js:172838

...and a whole lot more

We wanted to see where the problem was coming from, as step one. We commented out the es-header component and saw the app render. Then we commented out pieces of the app until we got to identifying search-input as the culprit.

The search feature of this app comes from a third-party library. Is something in there using process?

I enabled "Break on exceptions" in my browser's debugging tools. This showed us that indeed, process.env was being used in a third party script. But why did this work before? What else had changed?

Debugging webpack

The webpack errors are a clue about what changed. When we updated a bunch of things in package.json using ember-cli-update, one of them was ember-auto-import. This package uses webpack to bring npm dependencies into an Ember app with zero config, and we changed its versions.

One thing that changed was that certain polyfills were no longer included. This was outlined in the project README along with steps to fix it.

We added the following to our ember-cli-build.js:

autoImport: {
  webpack: { 
    node: { 
      process: 'mock'
    }
  }
},

Now, the app rendered successfully! We removed ?fastboot=false from our localhost URL, and saw that it was working fine in that mode too.

Up next

So, the app rendered, but the tests are failing. Coming soon, we'll tackle those test failures.

This is Part 3 of a series of blog posts. We're on a journey together to remodel an older Ember app, ember-api-docs, incrementally bringing it up to date with the latest and best Ember and Ember Data patterns.

For this series, I'm pair programming with Chris Thoburn, aka @runspired, who is known for his work on Ember Data. He has over 500 commits and some great debugging skills that you and I can learn from.

What you will learn in this segment

• How to run tests on-demand instead of on every change
• How to run the tests for different git branches, side by side
• What to expect in your test suite after upgrading the linters
• How to deal strategically and efficiently with hundreds of linting errors

Our progress so far

In the previous article, we had updated a bunch of dependencies and solved issues that prevented the app from building (build time errors) or prevented it from working correctly in the browser (runtime errors). We got to the end successfully, but there were some test failures.

Why were there failures? Well, we made a lot of changes! No matter what framework I'm using, any time I make a bunch of changes before running my test suite, I expect some tests to fail. Another path we could have chosen was to make changes one at a time, while running the test suite at every step. However, sometimes, seasoned Ember.js developers can take a big leap forward and then reconcile the errors. Sometimes, this latter approach saves you time, but if you get stuck, it's a good idea to take a step back and do one change at a time.

New tools for your toolkit - test running modes

Sometimes, the default behavior of ember test --server gets in the way. By default, the app rebuilds and test run every time you make a change. That wipes out the test failure information that you may need to reference while you make changes in multiple files.

Chris Thoburn showed me one way to improve on this experience and fix my test failures more quickly! He often runs a build continuously, and then in a separate process, run the tests. Although the app rebuilds every time you make a change, the test only re-run when you tell them to. So, the test failure output is always there when we need it.

# In one tab of your terminal, start the build and watch for changes
ember build --watch --output-path="./dist"

# In a new tab or window of your terminal, run the tests
ember test --serve --path="./dist" --no-launch

In these examples, we pointed the tests to the dist folder for the built app. We can apply this same strategy in order to run tests from different git branches side by side. For example, you could check out one branch of your app, run a single build, check out another branch, run a build, and then run the tests for both. Then you can inspect the results and compare them! You can even add debuggers to both branches and stop the test suites in the same place to inspect the state. Here's how!

git checkout main
yarn install
ember build --output-path="./dist-main"
git checkout upgrade-branch
ember build --output-path="./dist-my-upgrade-branch"
# Run the tests for main
ember test --serve --path="./dist-main" --no-launch
# Run the tests for the upgrade branch
ember test --serve --path="./dist-my-upgrade-branch" --no-launch

Resolving linting errors

One change we made was that we increased the version number of eslint-plugin-ember and ember-template-lint. When we did that, we brought in new linting rules for our .hbs templates and JavaScript files. We got automatic guidance on how we could improve our app's syntax, coding style, and most importantly, its accessibility. However, it means our linting tests were all failing with over 100 errors! How do we deal with that?

For every linting error or warning, we must choose between the following options:

• Update the codebase itself to resolve the warning
• Turn the rule off in .eslintric or .template-lintrc.js
• Add a code comment that tells the linter to ignore that file or line of code

Most of the time, when you are doing a dependencies upgrade, you should only fix very very tiny things and for everything else, ignore the rule and do the fixes themselves in later PRs. Why? We don't want to inadverdantly change the app's behavior! When upgrading dependencies, ideally the app looks the same when we're done.

Tools to help you deal with linting errors

There are some helpful tools in the Ember ecosystem for tracking and resolving linting issues over time, and they are especially important for large apps or teams.

First, ember-template-lint helps you automatically convert template linting errors into future to-do tasks. You can learn more about this feature in the Official Ember Blog.

Second, Chris Manson created lint-to-the-future, which turns all your errors into code comments that ignore the rule. When you fix a warning, remove the code comment. You can also visualize and measure your progress with some graphs!

Our approach

Although 100+ linting errors sounds like a lot, most of them were the same error over and over again. We could see them by running yarn lint.

We wanted to avoid making too many unnecessary changes in this app until after our upgrade step was over, so we turned a whole bunch of rules off in our .eslintrc. It makes sense that we had to turn off these rules, since many of them were telling us about how to turn our app into an Octane-style app. They will be useful after we finish the dependencies upgrade! We can learn more about each rule by searching for the rule name in the ember-cli-eslint source code.

// excerpt from .eslintrc
  rules: {
    'ember/no-jquery': 'off',
    'ember/no-jquery': 'off',
    'no-console': 'off',
    'ember/no-new-mixins': 'off',
    'ember/no-mixins': 'off',
    'ember/native-classes': 'off',
    'ember/require-tagless-components': 'off',
    'ember/no-test-this-render': 'off',
    'ember/no-classic-classes': 'off',
    'ember/no-get': 'off',
    'ember/no-actions-hash': 'off',
    'ember/no-classic-components': 'off',
    'ember/no-private-routing-service': 'off',
  },

We only needed to ignore two rules in our .template-lintrc.js. We can learn all about why these rules exist by searching for the rule name in eslint-plugin-ember source code. The file name matches the rule that shows up in the warnings. You can find it quickly on GitHub by pressing the letter T from the repository's main page and typing in the name of the rule.

// excerpt from .template-lintrc.js
rules: {
  'no-link-to-positional-params': false,
  'require-input-label': false,
  // and some more rules that were already there
}

require-input-label is an example of a linting rule that helps you discover accessibility issues in your app! It warns you if you have an input element that lacks an associated label element. In our case, this warning was a false hit - we found a bug! We reported the bug and linked to the public example of it.

no-link-to-positional-params was telling us not to do links in this style: {{link-to "About Us" "about"}}, Instead, we should do <LinkTo @route="about">About Us</LinkTo>. We can definitely handle this later.

Once our linting tests were passing, we moved on to the next step!

Understanding application test failures

When you do an upgrade like this, there are some common sources of failures. It's helpful to ponder this line of questioning below for a little when you run into a test that is tricky to fix:

• Did I make a mistake during the upgrade?
• Did the upgrade uncover a bug that was hidden previously?
• Were there any breaking changes in my dependencies?
• Was my app relying on a bug in Ember that was fixed?
• Did my app rely on private API methods?

After pondering this list, now I can move to the next level:

• What evidence do I have that my hypothesis is correct?
• Do I need to update a test, update something in my app, or both?
• If I reread the test failure again, do I get any new insights?

Our test failures

Here's an example test failure we worked through:

Error: Element not found when calling `fillIn('#ember-basic-dropdown-content-ember
1246 .ember-power-select-search-input[type=search]')`.
  at http://localhost:7357/assets/test-support.js:35450:15
  at async selectSearch (http://localhost:7357/assets/test-support.js:39374:9)
  at async Object.<anonymous> (http://localhost:7357/assets/tests.js:66:7)

In this case, the question that jumps out at us is "Were there any breaking changes in my dependencies?" We upgraded from ember-power-select version 2.3.5 to 4.1.6. Following the rules of semantic versioning, we can see that there have been two releases with breaking changes. Time to check the release notes of the library, in CHANGELOG.md. If you don't see a changelog for the library you are using, look at the Releases section on GitHub instead.

By reading the changelog, we could see that there was a new required attribute to add to the component. Adding @searchEnabled={{true}} to our power select dropdowns was all that was needed.

Another test failure we saw was this:

not ok 66 Chrome 91.0 - [196 ms] - Acceptance | document title: is of format className - version - Ember API Docs
  ---
    actual: >
        Ember Api Docs
    expected: >
        Container - 1.0 - Ember API Documentation

This was an example of a mistake we made while upgrading. The test that was failing was checking the page title of a certain URL in the app. A page's title is important for SEO, accessibility, and overall user experience. It's part of the text that shows up in a search result. It is the text that shows up at the top of your browser tab. And for people who use assistive tech, it helps them know what page they are on when they flip through tabs. You can learn more about page titles in the Ember Guides.

What happened was that when the upgrade diff was applied, it added something like {{page-title "EmberApiDocs"}} to the application.hbs template. Community member prakashchoudhary07 discovered that the page title was being set in another, more sophisticated way in this app, and they opened a PR to help us out. We could delete the page title helper, and the test passed. Thanks prakashchoudhary07!

Lastly, there was an error due to reliance on private API. One test was using private APIs on the router inside the test only. When I had tried to upgrade the test to use the router service instead, the method was no longer available. So, I undid the change I made during linting fixes and instead added an ignore to the eslint.rc. We can deal with that issue in another PR!

Up next

Now, all our tests are all passing! Next in this series, we will run some Octane codemods and refactor some components that are tough to work with. Thanks for reading!

I tried to imagine a future where Ember was wildly successful, not just surviving but growing, then work backwards to think through what those imaginary, wildly successful people must have done.

So, how did we do? Are we on-track to being the wildly successful people?

Being loud

Here's what I said a year ago about "Being Loud":

The people of Future-Ember worked to increase public awareness so that more developers knew about it and considered it for their projects. The Core Team led by example, writing and speaking, and the rest of the community was empowered to do the same.

I would wager that it's been a record year for this.

I know that a lot of core team members and cornerstone community members have given talks at non-Ember events and have done a ton of writing. 7/10 of my talks were at general venues like BostonJS and Boston Code Camp. Community members have also revived the emberjs subreddit. The official blog, once kind of a dead zone except for version releases, is now packed with evidence that Ember is on the move. The Ember Times team has their writing down to a science. The newest Ember.js Core Team member, Chris Garrett aka pzuraq is both an accomplished writer and someone who has helped ship a whole bunch of Ember's latest & greatest features. See posts here and here. In another example, core team member Melanie Sumner wrote an Accessibility Guide for the official Ember Guides, gave talks at accessibility-focused events throughout the year, and is working on framework code to make Ember better out-of-the-box for people who use assistive technology like screen readers. Jessica Jordan is speaking at this year's JSConf EU - a huge achievement - on web comics and animation. The list goes on and on.

Future-Ember provided approachable, current, convincing materials for new visitors.

A lot of this work has been completed, and the next 3 months will be the true testing grounds for its effectiveness.

Most notably, the outcome of the 2018 Roadmap process was this RFC, which introduced the first-ever "edition" of Ember, called Octane. Octane is currently in a preview period before its official release. The purpose of Octane is to pull together all the latest features of Ember into one cohesive (non-breaking) experience. It looks a whole lot more like regular JavaScript, with more explicit signals about which parts of an app are "special Ember things." Hopefully, as a result, it will be easier for new devs to pick up.

Being ready

Here's what I said was needed last year. Team… we did all of these. If you helped out with them, thank you so much.

A refactor of (at least) the first page of every topic within the Guides, to make them friendlier and more readable… Ember has a large group of community members who I believe are ready and willing to help out.

"Breaking" some of the Guides urls that have been held as canon.

While some things still need work, there were close about 400 Guides PRs over the past year. Four. Hundred. Along the way, I ended up writing an RFC to help jumpstart an even deeper set of revisions, and it was ultimately accomplished by over 40 contributors as part of work to prepare for the Octane preview.

Current addon authors could help lead a refactor of the CLI docs. Newer people can help with writing and making sure that the results are as helpful as possible.

This also had an RFC that described the plan. Again, over 40 people helped to migrate content from the old site, remove outdated/incorrect info, and write some new things. For example, we now have an official tutorial for anyone who wants to write an addon. It's all live at cli.emberjs.com. There's still work to do to clean up, like adding redirects from the old site, but we can do it!

Freshen up the look and feel of our main "marketing" resources like the home page.

The proposed website redesign looks phenomenal. It's inviting, modern, and really signals that Ember is something worth paying attention to. Sam Selikoff, Leah Silber, and others were instrumental to bringing this design to the forefront. People like Melanie Sumner, Chris Manson, and the Ember Learning Team laid the infra groundwork that makes it possible to do a full rebranding, thanks to some public website overhauls and the ember-styleguide.

Conclusion

I wouldn't have said this in previous years, but based on everything that's happened latey, I think we are actually on track to grow Ember's popularity and use. I'm constantly in awe of the trailblazing going on in this community, in terms of diversity, inclusion, accessibility, removing barriers to entry, maintainability, cooperation across national borders, and more. If people take notice of our tech, maybe they will take notice of these other things too, and spread them throughout the industry. Even if people don't use our code, maybe our work will still make things just a little bit better for everytone.

It's easier than ever to be optimistic.

This post is in response to Ember's Call for Roadmap Blog posts, and I invite you to write one of your own! What do you think Ember should focus on over the next year? I wrote one of these last year too, and you can read here about how Ember hit nearly all the goals I was hoping for!

What is the Ember Experience?

The ideal Ember Experience is that things work as they should out-of-the-box, following modern web development patterns. It's easy to get ramped up using real-world code examples that teach the recommended practices used by experienced Ember developers, from day one.

What do we need to fix or build so we can get there?

Let's teach people to use the things we're proud of

Take a look at Vue Vixen's library of open-source workshops. It's inspiring to see what it looks like when framework learning and teaching is done exceptionally well! While we may not have the same resources as other frameworks, whatever we have set as priorities, we have consistently achieved. I've heard other people say that the Ember Guides are great and some of the best docs out there, but we need to reach higher.

Why should teaching and documentation be a priority of the entire Ember organization? As many as 50% of visitors to the Ember Guides and Tutorials are visiting for the first time. (Either that, or a ton of you are very good about using Incognito mode on your browsers, or other tools that block Google Analytics.)

A problem to fix

There's a problem though. The majority of Ember's Core Team members have never done any writing for the Guides.

Thankfully, there are a zillion community members who help keep the guides up to date and improve them over time, at a pace of 30–40 PRs per month. Although it takes up most of my open source time, whatever time I spend on reviewing PRs is always time well spent, and I am so grateful for the participation.

However, the voice of Ember's leadership is largely missing from the materials that are most often used.   Everyone has their area of specialization, and many core team members do their own kind of docs writing for the APIs, deprecations, etc, but I think we need to do better. Even inside the learning core team, we're not focused on long-lived, most-used content. The group focus is on website infra and the Times newsletter. Only a couple people do most of the Guides work. We're off-balance, and we need more core team members to be engaged.

How to move the needle

These are the main areas where we could make some changes:

1. We could make documentation and learning be a focus for 2019–2020, meaning that the core teams would commit to doing more work to help teach the tools that we are all guiding and building. 
2. We add more writing-focused people to the core teams (all four teams)
3. We support the creation of "less official" Ember resources, which could serve as a training ground for new writers. It's hard writing within the constraints of the Guides, so cultivating other resources is good practice and enriches the knowledge base. The Guides are the "happy path" but we need other places that document the weird stuff.
4. We do a better job of collaborating with community members who could help with big changes. There's too much risk currently for most non-core people to do something like devote a full week to helping revise docs- would their work ever get merged? Or will it get lost in back & forth about the right way to teach Ember? I'm willing to be a bit reckless with the Guides merge button, but the rest of the teams need to be on board.
5. We set a specific, time-based goal of writing another Ember Tutorial to go with Super Rentals and the Quickstart. If there are no community volunteers, we do it ourselves.
6. We consider granting PR review & merge abilities to non-core team members, for the Guides only. This distributes review responsibility so that seasoned writers/reviewers can spend more time planning the next big steps, getting new writers involved, and writing itself.
7. We get some kind of code block tests in place. We burn a lot of time fixing formatting and mistakes that could be caught by a JavaScript parser. It's more "infra" work, but in direct service of learning quality, and recaptures some time burned by the current writers & maintainers.

There are some downsides to these points. If core team members were to help more with the guides, it would mean they were doing less of something else. What can we cut? What can we do more efficiently? Which things can become the responsibility of someone else, through mentorship and leadership as opposed to individual contributions? Who is bored of what they are doing, or has been uninvolved lately, and wants to try something new? This will take discussion.

Embrace the land of copy-paste

Another achievable, realistic way to level up the guides is to give better code examples. Copying and pasting code is an important part of how people learn and work, so our resources should make that easy and safe to do.

Today, if you copy and paste from Ember's official Guides, there are problems. For example, the Guides show input text boxes over and over, but only a small percentage of those samples have a <label>. Sure, the article focus is on teaching how to use the component, not how to write HTML. However, if we assume that most people will copy and paste, and we want Ember users to follow best practices for the web, we should step up our game. There are a ton of little mistakes like that which impact accessibility, for example, plus browser compatibility.

More real-world examples

To that end, we should create more real-world examples for Ember and make them available to our users. For example, we teach how to use form inputs, but not how to make a fully-functional, accessible form. A long time ago, there was a section of the Guides called the Cookbook which tried to do this, but it was unmaintained and eventually removed. The only way we can deliver is if we have more people engaged in writing and maintaining Ember's documentation and tutorials, at a deep level.

Accessibility as a framework feature

Accessibility is a big theme in Ember lately, and I'm a huge fan of any progress in that area. Since Ember covers so much of the concerns of front end development, it's not a giant leap to roll accessibility into Ember's out-of-the-box experience.

A focus on accessibility gives Ember a competitive edge that can attract companies who must follow accessibility standards, and developers who care about making their work usable by everyone. Our outside image is important, and how people feel while using Ember apps is important.

As a long-lived library and community, we get the chance to solve the really hard problems, the kinds of things that can change the web. We should make that happen.

To give some concrete examples, I think the accessibility linting rules were a huge success, and we should make the next moves to incorporate ember-a11y tools as the standard. We could become the leader among SPA frameworks for solving things like changing routes in a way that screen readers understand. 

For more on this, read Yehuda Katz' 2019 Roadmap Blog Post as well as Melanie Sumner's post from last year.

Business use case

These aspects of Ember have a real impact on my work at Cardstack. Ember.js is a key dependency of the Card SDK. Any improvements we make to the Ember Guides will help me teach Cardstack to new devs. Any improvements we make to accessibility help our products gain traction with enterprise customers.

Other companies benefit in the same way on the accessibility front. When it comes to learning materials, there's a real cost to not investing in this area, since most companies using Ember train at least some of their developers in-house. It's totally reasonable for a dev with experience in React, Vue, or Angular to learn Ember quickly. We have an opportunity to make onboarding easier for these companies, and if we do it well, new teams who want to adopt Ember can confidently do so.

How to participate in the Roadmap

Please write your own blog post for the Ember 2019 Roadmap! Even if it's just to say you agree/disagree with someone else, we want to hear your voice. It has a bearing on the outcome. Thanks for reading!