Catch up latest docs: from 5.1 to 5.4 (#215)

* feat: implement the catch up automation script

* feat: automatic catch up from 5.1 to 5.4

guides/code-editors/index.md

@@ -7,12 +7,13 @@ many of which are created and maintained by the developer community:
 Visual Studio Code is a code editor optimized for building and debugging modern web applications.
 Visual Studio Code is one of the most popular text editors among Ember developers.
 
-### Syntax Highlighting
+### Extension Pack
+
+Install the extension pack to get everything you need to work on Ember.js projects.
 
-Only one of these is needed.
+[Ember.js Extension Pack](https://marketplace.visualstudio.com/items?itemName=EmberTooling.emberjs) - It will install the following addons
 
-[VSCode Glimmer](https://marketplace.visualstudio.com/items?itemName=chiragpat.vscode-glimmer) -
-Provides embedded template highlighting support.
+### Syntax Highlighting
 
 [Glimmer Templates Syntax](https://marketplace.visualstudio.com/items?itemName=lifeart.vscode-glimmer-syntax) -
 Syntax formatting for glimmer templates.
@@ -22,10 +23,9 @@ Syntax formatting for glimmer templates.
 [Stable Ember Language Server](https://marketplace.visualstudio.com/items?itemName=lifeart.vscode-ember-unstable) -
 Stable Ember Language Server is a stable, full-featured language server. Its name comes from its history as a fork of Ember Language Server and the efforts to keep up with changes in Ember.
 
-### Snippets / Workflow
+### Workflow
 
-[Ember JS (ES6) and Handlebars code snippets](https://marketplace.visualstudio.com/items?itemName=phanitejakomaravolu.EmberES6Snippets) -
-Enables Ember.js and Handlebars snippets to let you to type less and code more.
+[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Integrates ESLint into VS Code.
 
 [EditorConfig for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) -
 Attempts to override user/workspace settings with settings found in `.editorconfig` files.
@@ -35,9 +35,21 @@ and maintain consistent coding styles between different editors and IDEs.
 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -
 Prettier is an opinionated code formatting tool. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary. Prettier supports Handlebars, Ember and Glimmer out of the box.
 
-### Glimmer templates
+### Typed Glimmer Templates
+
+<div class="cta">
+  <div class="cta-note">
+    <div class="cta-note-body">
+      <div class="cta-note-heading">Zoey says...</div>
+      <div class="cta-note-message">
+        This is not installed as part of the extension pack but should be considered for Ember projects built with TypeScript. Learn more about <a href="https://typed-ember.gitbook.io/glint/">Glint here</a>.
+      </div>
+    </div>
+    <img src="/images/mascots/zoey.png" role="presentation" alt="">
+  </div>
+</div>
 
-[Glint](https://marketplace.visualstudio.com/items?itemName=typed-ember.glint-vscode) is a set of tools to aid in developing code that uses the Glimmer VM for rendering, such as Ember.js v3.24+ and GlimmerX projects. 
+[Glint](https://marketplace.visualstudio.com/items?itemName=typed-ember.glint-vscode) is a set of tools to aid in developing code that uses the Glimmer VM for rendering, such as Ember.js v3.24+ and GlimmerX projects.
 
 ## Vim and Neovim
 
@@ -63,10 +75,10 @@ or
 [vim-ember-hbs](https://github.com/joukevandermaas/vim-ember-hbs) -
 Add Ember template syntax highlighting and indentation to Vim.
 To get embedded highlighting will involve these additional plugins:
+
 - [vim-javascript](https://github.com/pangloss/vim-javascript)
 - [vim-js-pretty-template](https://github.com/Quramy/vim-js-pretty-template)
 
-
 ### Language Server
 
 Only one of these solutions should be used at a time.
@@ -78,21 +90,18 @@ Example mason+LSP config [can be found here](https://github.com/NullVoxPopuli/do
 or
 
 [Conquer for Completion (COC) for Neovim](https://github.com/neoclide/coc.nvim) -
-An Intellisense engine which takes control over all linting, hinting, and language-server integration.
+An IntelliSense engine which takes control over all linting, hinting, and language-server integration.
 With the ember plugin [coc-ember](https://github.com/NullVoxPopuli/coc-ember) -
 Ember.js language server extension including useful configuration instructions.
 
 ### Snippets / Workflow
 
-
 [ember.vim](https://github.com/dsawardekar/ember.vim) -
 Shortcuts to navigate related files with Ember.js projects.
 
-
 [Ember Tools](https://github.com/AndrewRadev/ember_tools.vim) -
 Various tools for working with Ember.js projects.
 
-
 ## Atom
 
 Atom is hackable text editor for the 21st Century.

guides/components/template-lifecycle-dom-and-modifiers.md

@@ -293,10 +293,17 @@ The modifier that we're going to build will allow us to say:
 
 Pretty nice, right?
 
-To accomplish that, we'll create a modifier in `app/modifiers/autofocus.js`. First, install [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) and then generate an `autofocus` modifier for your app:
+New Ember apps ship with a dependency on
+[ember-modifier](https://github.com/ember-modifier/ember-modifier), which
+provides a friendly API for writing your own element modifiers. This library is
+in turn based on a low level API named _modifier managers_. Managers are a
+framework-development level feature, and not something most developers need to
+interact with. You'll see in the following examples that the modifier API is
+imported from the `ember-modifier` package.
+
+First generate the `autofocus` modifier for your application:
 
 ```bash
-ember install ember-modifier
 ember generate modifier autofocus
 ```
 
@@ -308,9 +315,10 @@ import { modifier } from "ember-modifier";
 export default modifier(element => element.focus());
 ```
 
-And that's it!
+And that's it! Now we can use our custom `{{autofocus}}` modifier throughout our application.
 
-Now we can use our custom `{{autofocus}}` modifier throughout our application.
+Read more about the `ember-modifier` APIs at [ember-modifiers:
+Usage](https://github.com/ember-modifier/ember-modifier#usage).
 
 ## Communicating Between Elements in a Component
 
@@ -390,7 +398,6 @@ export default class AudioPlayerComponent extends Component {
 That's it for the component: we're translating the user's interactions into _state_. Now we need to build a modifier to translate the state into the appropriate DOM method calls!
 
 ```bash
-ember install ember-modifier
 ember generate modifier play-when
 ```
 
@@ -448,12 +455,11 @@ document.addEventListener("click", event => {
 
 The most important difference between this example and the cases we've seen so far is that we need to remove the `click` event handler from the document when this element is destroyed.
 
-To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. 
+To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) (which is already installed in newly generated Ember apps) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. 
 
-Run the following commands to install the addon and generate a new modifier:
+Generate the new modifier:
 
 ```bash
-ember install ember-modifier
 ember generate modifier on-click-outside
 ```
 

guides/testing/index.md

@@ -34,7 +34,7 @@ ember t -s
 
 When you are working on a single component or page, you will want only a small subset of tests to run after every file change. To specify which tests to run, you can add `--module` or `--filter` option to your command.
 
-The `--module` option allows you to select a **module**—a group of tests that you specified in `module()` in QUnit, or `describe()` in Mocha.
+The `--module` option allows you to select a **module**—a group of tests that you specified in `module()` in QUnit.
 
 ```bash
 # Button component example
@@ -44,7 +44,7 @@ ember test --server --module="Integration | Component | simple-button"
 ember t -s -m="Unit | Service | location"
 ```
 
-The `--filter` option is more versatile. You can provide a phrase to match against the modules and test descriptions. A test description is what appears in `test()` in QUnit, or `it()` in Mocha.
+The `--filter` option is more versatile. You can provide a phrase to match against the modules and test descriptions. A test description is what appears in `test()` in QUnit.
 
 ```bash
 # Button component example
@@ -57,7 +57,7 @@ ember t -s -f="Dashboard"
 ember t -s -f="Integration"
 ```
 
-In QUnit, you can exclude tests by adding an exclamation point to the beginning of the filter, e.g. `ember test --filter="!Acceptance"`. In Mocha, `ember test --filter="Acceptance" --invert`.
+In QUnit, you can exclude tests by adding an exclamation point to the beginning of the filter, e.g. `ember test --filter="!Acceptance"`.
 
 To learn more about options for testing, you can visit [Ember CLI Documentation](https://ember-cli.com/testing) or type `ember help test` in the command line.
 

guides/testing/testing-tools.md

@@ -164,6 +164,6 @@ While we don't recommend this practice in general, you might also use Percy in l
 
 ## Summary
 
-Ember provides easy paths to integrate QUnit and Mocha, also it supports a variety of addons and debugging tools to improve your developer experience in testing.
+Ember provides easy paths to integrate QUnit and it also supports a variety of addons and debugging tools to improve your developer experience in testing.
 
 In the next section, we will study 3 types of tests that Ember supports—unit, rendering, and application tests. We will look at each type and when you might use one over another.

guides/typescript/additional-resources/faq.md

@@ -0,0 +1,89 @@
+## What about missing types?
+
+### Gradually typing your app
+
+See ["Gradual Typing Hacks"][gradual-typing-hacks] for strategies for incrementally adding types to your app.
+
+### Install types for libraries
+
+You'll want to use library type definitions as much as possible. Many packages ship their own type definitions, and many others have community-maintained definitions from [DefinitelyTyped][], available in the `@types` name space. The first thing you should do is to look for types from other libraries: it will mean using fewer ["Gradual Typing Hacks"][gradual-typing-hacks] and getting a lot more help both from your editor and from the compiler.
+
+### The `types` directory
+
+During installation, we create a `types` directory in the root of your application and add a [`"paths"`][tsconfig-paths] mapping to your `tsconfig.json` that includes that directory in any type lookups TypeScript tries to do. This is convenient for a few things:
+
+- global types for your project (see the next section)
+- writing types for libraries that do not have any types
+
+These are all fallbacks, of course, you should use the types supplied directly with a package when possible.
+
+#### Global types for your project
+
+At the root of your application or addon, we include a `types/<your project>` directory with an `index.d.ts` file in it. Anything which is part of your project but which must be declared globally can go in this file. For example, if you have data attached to the `Window` object when the page is loaded (for bootstrapping or whatever other reason), this is a good place to declare it.
+
+We automatically configure `index.d.ts` to be ready for [Glint][], which will make type checking work with Ember's templates. The default configuration only supports Ember's classic pairing of separate `.ts` and `.hbs` files, but Glint also supports the `<template>` format with `.gts` files. See the [corresponding package README][glint-environment-ember-template-imports] for more details. (Once Ember enables `<template>` by default, so will our Glint configuration!)
+
+### Environment configuration typings
+
+Along with the `@types/` files mentioned above, we add a starter interface for `config/environment.js` in `app/config/environment.d.ts`. This interface will likely require some changes to match your app.
+
+We install this file because the actual `config/environment.js` is (a) not actually identical with the types as you inherit them in the content of an application, but rather a superset of what an application has access to, and (b) not in the same location as the path at which you look it up. The actual `config/environment.js` file executes in Node during the build, and Ember CLI writes its result as `<my-app>/config/environment` into your build for consumption at runtime.
+
+## Type Narrowing with Ember Debug Assert
+
+Ember's `assert` function from `@ember/debug` is super useful for ["type narrowing"][type-narrowing]—TypeScript's process of refining types to more specific types than originally declared. If you're not familiar with `assert`, you might want to take a look at its [API docs][debug-assert]! It's a development-and-test-only helper that gets stripped from production builds, and is very helpful for this kind of thing!
+
+For example, let's pretend we're writing an addon that provides a `totalLength` helper to tally up the total length of an array of strings passed to it. Because addon authors cannot guarantee that their users will be using TypeScript, we've typed the positional arguments as an array of `unknown` so that TypeScript will ensure we've handled every possible valid or invalid argument a user might pass.
+
+We can use `assert` to ensure that if a user passes an array containing non-string values, our addon will error in tests and development.
+
+```typescript
+import { assert } from '@ember/debug';
+
+function totalLength(positional: unknown[]) {
+  assert(
+    'all positional args to `total-length` must be strings',
+    positional.every((arg): arg is string => typeof arg === 'string')
+  );
+
+  // TypeScript now knows that `positional` is a `string[]` because we asserted above
+  return positional.reduce((sum, s) => sum + s.length, 0);
+}
+```
+
+And, the types for `assert` ensure that TypeScript can use the condition you pass to properly narrow the types, because `assert` is typed as an [assertion function][assertion-function].
+
+```typescript
+export interface AssertFunc {
+  (desc: string, condition: unknown): asserts condition;
+  (desc: string): never;
+}
+```
+
+## Strictness
+
+You can enable TypeScript's current strictest configuration by including the `@tsconfig/strictest` base _before_ the `@tsconfig/ember` base in your `tsconfig.json`:
+
+```json5 {data-filename="tsconfig.json" data-diff="+3"}
+{
+  extends: [
+    '@tsconfig/strictest/tsconfig.json',
+    '@tsconfig/ember/tsconfig.json',
+  ],
+  // ...
+}
+```
+
+<!-- Internal links -->
+
+[gradual-typing-hacks]: ../../application-development/converting-an-app/#toc_gradual-typing-hacks
+
+<!-- External links -->
+
+[assertion-function]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+[debug-assert]: https://api.emberjs.com/ember/release/functions/@ember%2Fdebug/assert
+[DefinitelyTyped]: https://github.com/DefinitelyTyped/DefinitelyTyped
+[glint-environment-ember-template-imports]: https://github.com/typed-ember/glint/tree/main/packages/environment-ember-template-imports#readme
+[glint]: https://typed-ember.gitbook.io/glint
+[tsconfig-paths]: https://www.typescriptlang.org/tsconfig#paths
+[type-narrowing]: https://www.typescriptlang.org/docs/handbook/2/narrowing.html