upgrade-guide

This is a working repository for the Ember Upgrade Guide.

Prerequisites

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

Installation

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

Running / Development

ember serve
Visit your app at http://localhost:4200.
Visit your tests at http://localhost:4200/tests.

Running Tests

npm test
npm test --server

Linting

npm run lint
npm run lint:fix

Building

npm build (production)

Deploying

Specify what it takes to deploy your app.

Code Generators

Please use Ember CLI to create files in the app folder. You can run ember help generate for more detail.

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
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:

Contributing

Have a look at open issues.

Contributors

Abhilash LR
Jenny Judova
Kenneth Larsen
Robert Jackson

fozy81/upgrade-guide