How to upgrade an Ember App or Addon

At a high level, there are three steps to this upgrade process:

1. Upgrade all forwards-compatible packages
2. Upgrade 3rd-party dependencies and addons, one at a time
3. Upgrade Ember CLI and friends using ember-cli-update

The best part of this process is that you always know what your next step is, and you can even stop halfway through and pick back up where you left off weeks later.

Step 1: Upgrade forwards-compatible packages

By using

yarn upgrade-interactive --latest

and selecting the green and yellow packages, you can quickly identify which dependencies have forwards-compatible updates to make. After upgrading all these packages, run your test suite and verify your app works.

Congrats! You just knocked out step 1 of the upgrade.

Step 2: Upgrade 3rd-party dependencies and addons, one at a time

The next step is to upgrade your 3rd-party dependencies, one at a time.

To help you figure out which deps are 1st-part, you can use the ember-new-output repo for apps (and the ember-addon-output repo for addons). Using these repos, you can select the current version of your project and see which dependencies were included by default by Ember CLI. You can then ignore these and focus on your 3rd-party dependencies for this step.

Once you find your first outdated 3rd-party dependency, open its project page, and look for a CHANGELOG or at the releases tab to identify what has changed between your current version and the latest version. Make the necessary changes, install the new version, and run your tests suite. You may need to fix some things to accommodate new APIs or breaking changes.

Once you have your test suite passing with the new version of this single dependency, create a commit. You've just upgraded one dependency, and have a passing test suite! Time to move to the next 3rd-party dependency.

This step may take some time, but at any point you could merge this PR in, since the test suite is green after every update. If you need to step away from the upgrade to do product work, don't worry about it – merge the PR, work on your feature, and when you come back, you can use the exact same process and pick up right where you left off.

Step 3: Upgrade Ember CLI and friends with ember-cli-update

The final step is to install Ember CLI Update and use it to upgrade your project.

To be safe, upgrade from one LTS to the next. For example, if you're on 2.16, first go to 2.18, then 3.4.

ember-cli-update --to 2.18

This tool takes care of the annoying parts of an upgrade – changing Ember CLI's autogenerated blueprint files to match their new versions. You will run into git conflicts, so fix them as usual.

Once you fix all conflicts, make a commit, and then start working on getting your test suite passing. You may have new linter failures or other breakages due to new APIs. Follow the deprecation warnings and errors, and look at Ember, Ember CLI and Ember Data's changelogs to help guide you through the changes you need to make to your app code.

---

Using this process you can amortize the cost of an upgrade over time, so that if higher-priority tasks sneak up you won't feel pressured to completely abandon the upgrade and lose a lot of work. Just commit what you have, and come back to finish the upgrade when you have time!