What you need to know before migrating to a new version of Ember
Prerequisites: To comprehend the article in its entirety, you should have a working knowledge of JavaScript and frameworks.
Ember, the open-source JavaScript web framework, has a strong presence at Freshworks.
While we use many industry standard JavaScript frameworks in our products, we use Ember for most of our front-line products. Ember provides the reliability and performance of a RAILS-like framework, and consequently, we can ship features faster through a convenient and conventional setup. The tool enables the company’s engineering team to focus on building new capabilities rather than spending time on making trivial decisions on choosing tools and libraries. This Convention over Configuration (CoC) model is a true productivity booster for large development teams within Freshworks.
In this post, we talk about semantic versioning, Ember deprecations, how Ember manages its deprecations, and the knowledge necessary to migrate your Ember apps to a new Ember version.
Ember deprecations follow semantic versioning
Ember, like any other framework, periodically deprecates some of its APIs. To migrate your Ember code base to a new version, it is important to understand how Ember.js releases new APIs and deprecates old ones. During a minor release, the apps that use the deprecated APIs continue to work, but deprecation warnings are displayed on the console. Until a major version is released, handling of such deprecations through warning messages are supported by the Ember community. After the major revision, the supporting code may be removed and the apps may not work till the APIs are replaced.
Under the semantic versioning scheme, version numbers and the way they change indicate the underlying code and convey what has been modified from one version to the next.
Backward compatibility with the Ember CLI
To deliver an Ember.js app or add-on, you can use the Ember CLI tool to create, build, test, and publish the app or add-on. The Ember CLI circumvents configuration and provides an easy-to-use environment for the applications to move from development to production. Open source plugins for the CLI are available and these plugins automate tasks such as upgrading an app to the latest Ember framework version. The CLI tool is also backward compatible and therefore a new version of the CLI can be used with an existing Ember app.
If you have an Ember app whose codebase is not migrated to support the API deprecations, you can upgrade the command line utility to compile and run the app such that it does not break. You should resolve issues around deprecations, as issues arise, so that when a major version is available, it’s easier to upgrade an app. Before you migrate your codebase to perform significant changes, verify the Release Blog Posts to see if the appropriate codemods are available.
Ember deprecations
Let’s take two examples of Ember deprecations. The first one is a simple deprecation that replaces two existing APIs with one API. The second is a slightly complex deprecation to address because it requires significant revamping of the code apart from replacing the old APIs with new APIs.
Example1: Property change deprecation (version 3.1)
To support the deprecation, all we need to do is to remove the propertyWillChange statements and replace the old propertyDidChange API with the new notifyPropertyChange API. These kind of simple transformations can be handled by the search and replace functionality of a code editor.
The transformed code
Example2: Router events deprecation (version 3.6)
In this deprecation, we need to modify the code base significantly – copy the functionality of the willTransition and didTransition hooks, remove the webhooks, move the functionality to the init function, configure appropriate event listeners, and so on. The changes cannot be done with the simple find and replace functionality.
The transformed code
With manual effort, the migration from one minor version to the next will take weeks to deploy, and it could take several months to complete if it is a major version. Also, larger the code base, the more time it takes.
The best way to handle such transformations is to use automated codemod tools that convert the source code into a tree format such as the Abstract Syntax Tree (AST), make the necessary modifications with the tree nodes, and reconvert the modified tree to the source code. It is easy to work with tree data structures to insert, update, and modify nodes than to work with the source code in plain text format; therefore, the codemod tools make refactors easy.
Watch this space for the second part of this series of blogs. We’ll talk about how Codemods are the new-age saviours for JS developers, and will delve into the details of codemods, ASTs, and how they help migrate codebases.
