upgrade-guide

This is a working repository for the Ember Upgrade Guide.

Prerequisites

You will need the following things properly installed on your computer.

• Git
• Node.js (with npm)
• Google Chrome

Installation

• git clone <repository-url> this repository
• cd upgrade-guide
• npm install

Running / Development

• npm run start
• Visit your app at http://localhost:4200.
• Visit your tests at http://localhost:4200/tests.

Code Generators

Make use of the many generators for code, try npm exec ember help generate for more details

Running Tests

• npm run test

Linting

• npm run lint
• npm run lint:fix

Building

• npm exec vite build --mode development (development)
• npm run build (production)

Deploying

Specify what it takes to deploy your app.

Adding the latest Ember version

When a new version of Ember is released (for example, version 3.20), we need to manually update this app. Let's look at how to provide information on version number, features, and deprecations.

First, we add the version number to the VERSIONS array:

// app/utils/ember-versions.js

export const VERSIONS = Object.freeze([
  '1.0 Prerelease',
  ...
  '3.19',
  '3.20', // <-- new!
]);

Next, we use custom blueprints to create Markdown files that can list features and deprecations for Ember.js, Ember Data, and Ember CLI.

# Creates 3 Markdown files in the `source` directory
npm exec ember generate upgrade-notes 3.20

Each Markdown file, by default, lists 1 deprecation and 1 feature:

---
version: "3.20"
changes:
  -
    deprecation: true
    title: ""
    link: ""
  -
    feature: true
    title: ""
    link: ""
---

If the release has no deprecations (or no features), you can delete the default item. If the release has more than 1 deprecation (or more than 1 feature), you can copy-paste the default item to list all.

For example, Ember CLI v3.20 has 2 deprecations and 1 feature. The Markdown file looks like,

---
version: "3.20"
changes:
  -
    deprecation: true
    title: "Usage on Node 13 will now issue a warning"
    link: "https://blog.emberjs.com/2020/07/29/ember-3-20-released.html"
  -
    deprecation: true
    title: "Usage of PACKAGER is deprecated"
    link: "https://blog.emberjs.com/2020/07/29/ember-3-20-released.html"
  -
    feature: true
    title: "Syncing Blueprints"
    link: "https://blog.emberjs.com/2020/07/29/ember-3-20-released.html"
---

⚠️ Please note that the value of version must be a string.

Where to find lists of features and deprecations

For consistency, we recommend relying on Ember Blog - Releases. If you want to learn more about a feature or deprecation, you can check the release notes and CHANGELOG in each project:

• ember.js
• Vite
• Development Browser Extensions
  • ember inspector for chrome
  • ember inspector for firefox

Contributing

Have a look at open issues.

Contributors

• Abhilash LR
• Jenny Judova
• Kenneth Larsen
• Robert Jackson