DEV Community: Jen Weber

Remodeling an Ember App - Codemods and jQuery

Jen Weber — Tue, 13 Jul 2021 21:33:37 +0000

When you need to upgrade and ember app, codemods can help you update your app's syntax faster than you could make changes by hand. Today, we'll talk about codemods and cover what to do about jQuery usage in your apps.

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!

Remodeling an Ember App - Testing

Jen Weber — Thu, 17 Jun 2021 02:41:01 +0000

Today's topic is debugging an Ember app's test suite after upgrading some dependencies. This is a real-world app and the issues we face will be different from your apps, but you can learn the overall strategy and debugging approaches,

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 only needed to add two rule ignores. 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 thus 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. Therefore, we could delete the page title helper, and the test passed.

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!

Remodeling an Ember App - Package Updates

Jen Weber — Wed, 09 Jun 2021 13:29:23 +0000

Today's topic is upgrading dependencies on an older Ember app. This is a real-world app and the issues we face will be different from your apps, but you can learn the overall strategy and debugging approaches,

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:

Upgrade addons
Upgrade core Ember and Ember Data dependencies

Or, they approach this in the reverse order:

Upgrade core Ember and Ember Data dependencies
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.

Remodeling an Ember App - Introduction

Jen Weber — Thu, 03 Jun 2021 14:06:37 +0000

In a series of blog posts, we'll go 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.

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

Thinkig 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 over the coming weeks. However, 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!