Ember upgrade v3.x to 4.x

A dev journey of Ember upgrade from v3.20 to 4.8

Every aspiring dev journey starts from documentation, a bunch of documentations.

Upgrade guide:

• https://cli.emberjs.com/release/basic-use/upgrading
• https://guides.emberjs.com/release/upgrading

Deprecation guide:

• https://deprecations.emberjs.com

Release guide:

• https://blog.emberjs.com/tag/releases

RFCs guide: Checkout to know more about behind the curtain of a deprecation

• https://rfcs.emberjs.com/#accepted

Upgrading a project is very ambitious task, and like every ambitious task let's break into small tasks.

Upgrade Plan

• Sequential upgrade LTS wise.
• Handle deprecation of only upgraded LTS.

How to upgrade?

Step 1: Upgrade ember-cli [as eg. 3.24.0 to 3.28.0]

  $ npm install -g ember-cli-update

  $ npm uninstall -g ember-cli
  $ npm install -g ember-cli@3.28.0
  $ ember --version

Step 2: Navigate to project path in terminal

$ cd <project-path>
$ ember-cli-update --to 3.28.0

This will update the project to the mentioned Ember CLI version. It will only modify the files if there are changes between your project's version and the latest version, and it will only change the section necessary, not the entire file.

You will probably encounter merge conflicts, in which the default behavior is to let you resolve conflicts on your own.

Step 3: Run your project to checkout any breakage [Project dependant]

Project third party packages can be upgraded while or even after upgrade of ember-cli, depends on project and type of breakage.

Detailed Ref: https://cli.emberjs.com/release/basic-use/upgrading

How to handle deprecation?
Step 1: Install ember-cli-deprecation-workflow in project

$ npm install ember-cli-deprecation-workflow --dev

Step 2: create config/deprecation-workflow.js
Step 3: Add deprecation message entries as per documentation

Dev note: Handling and maintenance of deprecation in large project becomes tedious, this is how I handled one deprecation/version-wise at a time.
Github link: https://github.com/rajforum/ember-upgrade-note/blob/main/deprecation-wokflow.js

Change handler to log to list deprecations and throw once fixed.

TLDR tip:

• There are codemods which reduce repetitive bulky changes.
  • https://github.com/orgs/ember-codemods/repositories
  • https://github.com/dyfactor/dyfactor-plugin-disambiguate-locals
• If you're jumping from 3.x to 4.x as 4.0.0 is not an LTS candidate even-though I would suggest to have 4.0.0 as internal-upgrade which handle all v3x deprecations.

A mention to other Refs which has helpful at very first upgrade.

• https://youtube.com/watch?v=8RW49QK_wI8
• https://www.youtube.com/watch?v=ToVdJjHiKco
• https://github.com/ember-cli/ember-new-output