One of the biggest fears I hear from Ember developers is how to deal with churn and deprecations in the framework. Let me start by dispelling one common myth:

Deprecations are stopping me from upgrading my app!

The thing to understand about deprecations in Ember is that the framework follows Semantic Versioning. For those who don’t know I’m talking about, let me quote a small portion of the SemVer 2.0.0 summary.

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
   
2. MINOR version when you add functionality in a backwards-compatible manner, and
   
3. PATCH version when you make backwards-compatible bug fixes.
   

Or, as it’s known in Ember, STICK.CARROT.WHOOPS.

This means that going from (for example) Ember 1.11 to 1.12 only introduces new functionality and bug fixes without removing the existing features your app relies on (unless you’ve utilized non-public methods). Furthermore, you should be able to go from any 1.x version to a higher 1.x without major issues, keeping in mind the above caveats about upgrading all at once. Obviously, it would be insanity to expect SemVer to never be violated throughout the history of a framework, but from what I’ve seen, the Ember team is strongly committed to this pattern.

Given that premise, I have a hard time empathizing with developers who complain about features being “suddenly” deprecated in Ember. After all, having a deprecation at all is in fact giving you advance warning of a yet-to-be-introduced breaking change which will not occur until the next MAJOR version (2.0.x, in this case). So while you shouldn’t ignore deprecations altogether, I don’t understand the mad rush to address every deprecation before upgrading. After all, nothing is stopping you from moving to the next version and then handling the warnings over time.

The Deprecation Path

Now, I won’t go into too much detail about dealing with specific deprecations; for the most part, they are well-documented on the Ember Deprecations page. In fact, let me make it even easier for you. Check out Ember-Watson, an incredibly useful addon that will automatically refactor your code for best practices and deprecations. It won’t handle everything for you, but there are several commands you are sure to find useful in keeping your project up to date with the latest community trends.

In my mind, the deprecation workflow has some very simple rules:

• Upgrade your app before dealing with deprecations. The code you have now works (presumably), so don’t opt-in to the new way of doing things until you are ready. It’s best not to introduce the uncertainty of further regression at the same time. Besides, if you discover that your app breaks simply from updating packages, you’ve likely found a regression in your dependencies rather than a problem with your own project.
  
• `ember install ember-cli-deprecation-workflow`
• Seriously. Do it.
• Deal with each kind of deprecation one at a time in separate Pull Requests. This will allow you to more easily test for regressions. If a particular deprecation is rampant in its frequency, consider breaking that refactor down into multiple PRs as well.
• Don’t ignore the warnings forever; if you have several upgrades worth of messages hounding your console when you eventually reach a major version, it’s going to feel like a monumental effort to refactor your code and make the leap.

If you didn’t get the hint above, you really need to check out Ember-CLI-Deprecation-Workflow. I’ve given you the link twice now, so no excuses. This addon has been cited by developers as being the only thing “that made the upgrade feel possible”. While I wouldn’t necessarily go that far, it’s certainly an irreplaceable part of this process; the package allows you to track the deprecation warnings you’re seeing and then suppress them from being displayed in your console, which accomplishes three very important things:

• It allows you to avoid the overwhelming feeling of tens, if not hundreds, of warning messages polluting your console every time you fire up the app.
  
• You can easily see when deprecations are introduced into your codebase as new features are developed, because they won’t get lost in the slew of older messages.
• Lastly, the list of warnings it maintains provides you with an actionable queue of deprecations that need to be addressed.

Inevitably, some of your deprecation warnings will come from third-party addons you depend upon. The deprecation workflow suggested above enables you to focus purely on patterns within your own code while separately opening issues or even PRs into dependent repositories to remove those deprecations as well. The setup (as outlined in the README) is quite simple:

1. Install the `ember-cli-deprecation-workflow` addon.
2. Run your test suite.
3. Run `deprecationWorkflow.flushDeprecations()` from your browser’s console.
4. Copy the string output into `config/deprecation-workflow.js` in your project.

As an added note, remember that unless your test coverage is amazing (>90%), it’s likely that running your test suite won’t reveal every warning. I suggest running the live app through all of your workflows and flushing deprecations a second time, then merging it with the test suite output.

All in all, Ember-CLI-Deprecation-Workflow is quite indispensable for creating a manageable deprecation workflow. If you’re performing your upgrades without this tool, Tomster help you.

By the Grace of Tomster! 

(I can’t create my own God Tomster without infringing on the trademark, so you get this lovely DeviantArt rendering instead.)

Let’s take this one step further, though. I fully recommend using `ember-cli-template-lint` in conjunction with ember-cli-deprecation-workflow. This addon will allow you to route your HTMLbars deprecations into the browser console where they can be caught by the deprecation workflow, allowing you to put all of your deprecations in the same place!

The 2.0 Path

The last hurdle I want to address is getting over the Ember 2.x hump. The main purpose of the 2.0 release is de-cruft-ification, or removal of deprecated code. This being a MAJOR release in SemVer means we do have to care about all of the previously announced deprecations; these warnings were heralding the eventual death of certain features, and that time is now. If you’ve been paying attention up to this point, you know what to do; addressing every deprecation warning should enable you to upgrade to Ember 2.0 without regression. Unlike most other frameworks, no new features were added in the initial 2.0 release, just a cleanup of outdated patterns/features that needed to make way for the future direction of Ember.

Even though the 2.x series marks a new era for Ember, the path to get there isn’t as scary as it seems. The core team (and the overall community) has done a great job laying out a step-by-step path to success, and bringing your app up to speed isn’t an insurmountable task. If you get stuck, there are plenty of resources at your disposal, many of which I will outline in my next series, Ember Library.

Good luck, Embereños. May all your fears be deprecated!

Special thanks to Thomas (@djvoa12), Spencer (@spencer516), and Ben (@bdvholmes) for reviewing this series and making great suggestions to improve it.

Catch up on the rest of this series with Upgrading Ember Part I & Part II.