Apply suggestions from code review

Co-authored-by: Steve Piercy <[email protected]>

docs/source/contributing/typescript.md

@@ -9,39 +9,43 @@ myst:
 
 # TypeScript
 
-TypeScript support (5.2.2) has been added to Volto core.
+```{versionadded} 17.0.0-alpha.22
+```
+TypeScript support has been added to Volto core.
 ESlint has been configured in order to accept code base written both in JavaScript and in TypeScript.
-The usage of TypeScript in projects and add-ons was possible already since Volto 14 and it's added as default in the project generator since Volto 17.
+TypeScript in projects and add-ons has been supported since Volto 14.
+It is now supported in the project generator by default.
 
 ## TypeScript in core
 
-The internal policy will be as follows:
+The internal policy for TypeScript support in Volto core will be as follows.
 
-- No existing code will be migrated at this point (eg. Volto 17.0.0 won't have any TypeScript present)
-- Code in core can be written in both JavaScript and TypeScript
-- In any case you are forced to migrate existing code to TypeScript
-- It's up to the developer to choose which one to use
-- In all cases use common sense and be aware of code that could potentially have to be backported
-- If the developer chooses TypeScript and the feature has to be backported, it's up to the developer to backport it to non-TypeScript version in legacy (eg. LTS) versions
+-   No existing code has been migrated.
+    Volto 17.0.0 has no TypeScript code present.
+    Only *support* for TypeScript has been added.
+-   Code in core can be written in either JavaScript or TypeScript, or both.
+-   You are not forced to migrate existing code to TypeScript.
+    It's your choice which one to use.
+-   If you need to backport code to a version of Volto before 17.0.0, you must make the code compatible without TypeScript.
 
 ## TypeScript learning resources
 
-[TypeScript Official Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+-   [TypeScript Official Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
 
-[TotalTypeScript React with TypeScript Free course](https://www.totaltypescript.com/tutorials/react-with-typescript)
+-   [TotalTypeScript React with TypeScript Free course](https://www.totaltypescript.com/tutorials/react-with-typescript)
 
-[TotalTypeScript Beginner's TypeScript Free course](https://www.totaltypescript.com/tutorials/beginners-typescript)
+-   [TotalTypeScript Beginner's TypeScript Free course](https://www.totaltypescript.com/tutorials/beginners-typescript)
 
 ## TypeScript in projects and add-ons
 
-It is possible to enable TypeScript support when developing you project with Volto.
-If you are using the Volto generator, this is the default, and you can already start using TypeScript in it.
+You can enable TypeScript support when developing your project in Volto.
+If you use the Volto generator, TypeScript is enabled by default, and you can already start using TypeScript in it.
 
 ### Enable it in your Volto 17 project
 
-If you are already using Volto 17 in your projects, using a boilerplate generated before Volto 17.0.0-alpha.27 and the generator 7.0.0-alpha.7 you can follow the following instructions:
+If you already use Volto 17 in your projects, using a boilerplate generated before Volto 17.0.0-alpha.27 and the generator 7.0.0-alpha.7, you can enable TypeScript support as follows:
 
-Make the following changes in your {file}`package.json`:
+Edit your {file}`package.json`:
 
 ```diff
 -    "lint": "./node_modules/eslint/bin/eslint.js --max-warnings=0 'src/**/*.{js,jsx}'",
@@ -65,11 +69,12 @@ Make the following changes in your {file}`package.json`:
 ```
 
 ```{note}
-Could be that after this, you experience hoisting problems and some packages can't be found on start.
+After making this change, you might experience hoisting problems and some packages can't be found on start.
 In that case, make sure you reset your `yarn.lock` by deleting it and start with a clean environment.
 ```
 
-In case that you want to use TypeScript in your projects, you'll need to introduce a `tsconfig.json` file in it, and remove the existing `jsconfig.json`. You can use the one provided by de generator as template, or use your own:
+To use TypeScript in your projects, you'll need to introduce a TypeScript configuration file {file}`tsconfig.json`, and remove the existing file {file}`jsconfig.json`.
+You can use the one provided by the generator as a template, or use your own:
 
 ```json
 {
@@ -104,12 +109,12 @@ In case that you want to use TypeScript in your projects, you'll need to introdu
 }
 ```
 
-If you are using `mrs-developer` in your project, update the command in `Makefile`:
+If you use `mrs-developer` in your project, update the command in {file}`Makefile`:
 
 ```diff
 --- a/Makefile
 +++ b/Makefile
-@@ -59,7 +59,8 @@ preinstall: ## Preinstall task, checks if missdev (mrs-developer) is present and
+@@ -59,7 +59,8 @@ preinstall: ## Preinstall task, checks if missdev (mrs-developer) is present and runs it
 
  .PHONY: develop
  develop: ## Runs missdev in the local project (mrs.developer.json should be present)
@@ -119,16 +124,15 @@ If you are using `mrs-developer` in your project, update the command in `Makefil
 ```
 
 ````{note}
-Do not forget to run `mrs-developer` after doing it, so the configuration gets in the right place (`tsconfig.json`) now.
-Run
+After editing your {file}`Makefile`, run `mrs-developer` with the following command, so the configuration gets in the right place ({file}`tsconfig.json`).
 ```shell
 make develop
 ```
 ````
 
 ### Enable it in a project not using Volto 17 yet
 
-If you have an existing project using a Volto version previous to Volto 17 (and above 14), and you want to use TypeScript on it, you need to install these additional dependencies in your project:
+To use TypeScript for an existing project in Volto versions 14.x-16.x, you need to install these additional dependencies in your project:
 
 ```shell
 yarn add --dev typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin @types/react @types/react-dom concurrently

docs/source/upgrade-guide/index.md

@@ -62,11 +62,21 @@ You still have the freedom to develop using JavaScript.
 It's your choice whether you want to do it in TypeScript.
 In the past, you could add TypeScript support for Volto add-ons.
 It's also available for projects now, if you upgrade dependencies (see next section).
+```{versionadded} 17.0.0-alpha.22
 ```
 
-If you want to support TypeScript in your projects, you should update your projects.
+We added full support of TypeScript in Volto core.
+
+No existing code has been migrated.
+You may write code in either JavaScript or TypeScript.
+The choice is yours.
 
-Make the following changes in your {file}`package.json`:
+Previously developers had the option to support TypeScript only in their Volto add-ons.
+Now it's available in Volto projects, as long as you upgrade your project dependencies.
+
+To support TypeScript in your projects, you must update your project as follows.
+
+Edit your {file}`package.json`:
 
 ```diff
 -    "lint": "./node_modules/eslint/bin/eslint.js --max-warnings=0 'src/**/*.{js,jsx}'",
@@ -90,11 +100,12 @@ Make the following changes in your {file}`package.json`:
 ```
 
 ```{note}
-Could be that after this, you experience hoisting problems and some packages can't be found on start.
+After making this change, you might experience hoisting problems and some packages can't be found on start.
 In that case, make sure you reset your `yarn.lock` by deleting it and start with a clean environment.
 ```
 
-In case that you want to use TypeScript in your projects, you'll need to introduce a `tsconfig.json` file in it, and remove the existing `jsconfig.json`. You can use the one provided by de generator as template, or use your own:
+To use TypeScript in your projects, you'll need to introduce a TypeScript configuration file {file}`tsconfig.json`, and remove the existing file {file}`jsconfig.json`.
+You can use the one provided by the generator as a template, or use your own:
 
 ```json
 {
@@ -129,12 +140,12 @@ In case that you want to use TypeScript in your projects, you'll need to introdu
 }
 ```
 
-If you are using `mrs-developer` in your project, update the command in `Makefile`:
+If you use `mrs-developer` in your project, update the command in {file}`Makefile`:
 
 ```diff
 --- a/Makefile
 +++ b/Makefile
-@@ -59,7 +59,8 @@ preinstall: ## Preinstall task, checks if missdev (mrs-developer) is present and
+preinstall: ## Preinstall task, checks if missdev (mrs-developer) is present and runs it
 
  .PHONY: develop
  develop: ## Runs missdev in the local project (mrs.developer.json should be present)
@@ -144,15 +155,16 @@ If you are using `mrs-developer` in your project, update the command in `Makefil
 ```
 
 ````{note}
-Do not forget to run `mrs-developer` after doing it, so the configuration gets in the right place (`tsconfig.json`) now.
-Run
+After editing your {file}`Makefile`, run `mrs-developer` with the following command, so the configuration gets in the right place ({file}`tsconfig.json`).
 ```shell
 make develop
 ```
 ````
 
 ### Upgrade ESlint and use `@babel/eslint-parser`
 
+```{versionchanged} 17.0.0-alpha.22
+```
 ESlint uses a library to parse the language under analysis.
 The one used was long deprecated and didn't supported both TypeScript and JavaScript.
 We upgraded the ESlint parser to use `@babel/eslint-parser`.