PR feedback

pages/heft/architecture.md

@@ -7,11 +7,11 @@ navigation_source: docs_nav
 ## Terminology
 
 Heft's operation is organized around the following concepts:
-- **action** - a Heft command-line name (as formalized by Rush Stack's [ts-command-line](https://www.npmjs.com/package/@rushstack/ts-command-line) system).  For example, the "test" action appears in the  `heft test --clean` command.  Actions are the user interface, essentially macros tailored for typical developer activities.
+- **action** - a Heft command-line verb (as formalized by Rush Stack's [ts-command-line](https://www.npmjs.com/package/@rushstack/ts-command-line) system).  For example, the "test" action appears in the  `heft test --clean` command.  Actions are the user interface, essentially macros tailored for typical developer activities.
 - **plugin** - a TypeScript class that implements the `IHeftPlugin` contract to provide arbitrary functionality.  Plugins are loaded optionally based on Heft's configuration.  You can create your own NPM package that exports custom plugins for Heft to use.  See [Core Plugins]({% link pages/heft/core_plugins.md %}) for a list of the built-in plugins.
 - **hook** - Heft leverages Webpack's [tapable](https://www.npmjs.com/package/tapable) system for enabling plugins to register handlers for various events during the build.
 - **task** - a Heft operation that produces an output, typically by invoking some tool.  For example, `typescript` and `eslint` are Heft tasks.  Unlike in other systems, Heft's tasks are not a coding contract or TypeScript interface; for example the `TypeScriptPlugin` implements three separate tasks (`typescript`, `eslint`, and `tslint`) whose code is closely integrated.
-- **stage** - a larger sequence of work encompassing multiple Heft tasks.  When invoking Heft, the command line typically selects a meaningful set of stages to run. The stage names are also used to group logging output.  Examples of Heft stages: "clean", "compile", "bundle", "test"
+- **stage** - a larger sequence of work encompassing multiple Heft tasks.  When invoking Heft, the command line typically selects a meaningful set of stages to run. The stage names are also used to group logging output.  Examples of Heft stages: "clean", "build", "test"
 
  
 > **Future plans:** Today Rush commands can only invoke Heft actions.  However, in the future we want to implement a "multiphase build" feature that will enable Rush to orchestrate more granular steps of work.  For example, once a library dependency has compiled its output, Rush could start building the application before the library finishes running its unit tests.  This feature will bring some additional jargon:

pages/heft/core_plugins.md

@@ -8,11 +8,11 @@ navigation_source: docs_nav
 | ------------- | ------------- |
 | [ApiExtractorPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ApiExtractorPlugin/ApiExtractorPlugin.ts) | Implements the [api-extractor]({% link pages/heft_tasks/api-extractor.md %}) task |
 | [BasicConfigureWebpackPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/Webpack/BasicConfigureWebpackPlugin.ts) | Used to configure the [webpack]({% link pages/heft_tasks/webpack.md %}) task by loading a static **webpack.config.js** file (instead of building a dynamic configuration at runtime) |
-| [CleanPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CleanPlugin.ts) | Deletes temporary files from a previous build |
+| [CleanPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CleanPlugin.ts) | Deletes output files from a previous build |
 | [CopyStaticAssetsPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CopyStaticAssetsPlugin.ts) | Implements the [copy-static-assets]({% link pages/heft_tasks/copy-static-assets.md %}) task |
 | [JestPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JestPlugin/JestPlugin.ts) | Implements the [jest]({% link pages/heft_tasks/jest.md %}) task |
 | [PackageJsonConfigurationPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/PackageJsonConfigurationPlugin.ts) | Disables the [typescript]({% link pages/heft_tasks/typescript.md %}) tasks's symlinking optimization for published projects, because publishing workflows do not handle symlinks properly |
-| [ProjectActionConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ActionConfigurationLoaders/ProjectActionConfigurationFilesPlugin.ts)  | Reads project-specific config files for Heft "actions" such as **clean.json**, **typescript.json**, **copy-static-assets.json**, and **webpack.json** |
-| [RushActionConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ActionConfigurationLoaders/RushActionConfigurationFilesPlugin.ts)  | Reads Rush monorepo config files for Heft "actions" such as **clean.json**, **typescript.json**, **copy-static-assets.json**, and **webpack.json** |
+| [ProjectJsonConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JsonConfigurationLoaders/ProjectJsonConfigurationFilesPlugin.ts)  | Reads Heft-specific config files that apply to a single project. |
+| [RushJsonConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JsonConfigurationLoaders/RushJsonConfigurationFilesPlugin.ts)  | Reads Heft-specific config files that are shared across all projects in a monorepo. |
 | [TypeScriptPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/TypeScriptPlugin/TypeScriptPlugin.ts) | Implements the [typescript]({% link pages/heft_tasks/typescript.md %}), [eslint]({% link pages/heft_tasks/eslint.md %}), and [tslint]({% link pages/heft_tasks/tslint.md %}) tasks |
 | [WebpackPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/Webpack/WebpackPlugin.ts) | Implements the [webpack]({% link pages/heft_tasks/webpack.md %}) task |

pages/heft_configs/typescript_json.md

@@ -50,7 +50,7 @@ navigation_source: docs_nav
   // "disableTslint": true,
 
   /**
-   * Set this to change the maximum number of file handles that will be opened for writing.
+   * Set this to change the maximum number of file handles that will be opened concurrently for writing.
    * The default is 50.
    */
   // "maxWriteParallelism": 50

pages/heft_tasks/api-extractor.md

@@ -30,6 +30,7 @@ We recommend to use API Extractor for every TypeScript library project, especial
 
 There isn't a Heft-specific file for this task.  Heft looks for API Extractor's config file [config/api-extractor.json](https://api-extractor.com/pages/commands/config_file/). This file can be created by invoking the [api-extractor init](https://api-extractor.com/pages/commands/api-extractor_init/) command.
 
+
 ## package.json dependencies
 
 None -- Heft loads the `@microsoft/api-extractor` package from the `@microsoft/rush-stack-compiler-*` bundle.  See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details.

pages/heft_tasks/copy-static-assets.md

@@ -6,6 +6,7 @@ navigation_source: docs_nav
 
 This is a lightweight task that simply copies input files into output folders.
 
+
 ## When to use it
 
 This task is mainly used to copy assets into the compiler's target folder so that they can be referenced by compiled code.  In Heft's standard configuration, the TypeScript compiler reads **src/\*\*/.ts** inputs and writes **lib/\*\*/.js** outputs.  For example, a React project may have a file that loads an **src/index.css** asset like this:
@@ -29,6 +30,7 @@ When Webpack is invoked on **lib/index.js**, it will process the resulting `requ
 
 Configure this task using the [copy-static-assets.json]({% link pages/heft_configs/copy-static-assets_json.md %}) config file.
 
+
 ## package.json dependencies
 
 None - this feature is implemented internally by Heft.

pages/heft_tasks/eslint.md

@@ -6,9 +6,10 @@ navigation_source: docs_nav
 
 This task invokes the [ESLint](https://eslint.org/) tool which reports errors about common coding problems.
 
+
 ## When to use it
 
-ESLint fits together with several other tools as part of Rush Stack's strategy for code validation:
+ESLint fits together with several other tools as part of Rush Stack's recommended strategy for code validation:
 
 - [Prettier](https://prettier.io/): This tool manages trivial syntax aspects such as spaces, commas, and semicolons. Because these aspects normally don't affect code semantics, we never bother the developer with error messages about it, nor is it part of the build.  Instead, Prettier reformats the code automatically via a `git commit` hook (and also whenever you save a file, if you enable the editor extension).
 
@@ -18,6 +19,8 @@ ESLint fits together with several other tools as part of Rush Stack's strategy f
 
 - [API Extractor]({% link pages/heft_tasks/api-extractor.md %}): This is an additional validation check for library packages only.  It ensures their API contracts are well-formed and properly documented.
 
+Although it's recommended to set up your build system in this way, Heft doesn't require a particular approach.  Each of these components is optional, and other configurations are possible.  For example, older code bases may need to use [TSLint]({% link pages/heft_tasks/tslint.md %}) instead of ESLint.
+
 
 ## Config files
 
@@ -42,6 +45,7 @@ module.exports = {
 };
 ```
 
+
 ## package.json dependencies
 
 Heft loads the `eslint` package from the `@microsoft/rush-stack-compiler-*` bundle.  See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details.

pages/heft_tasks/jest.md

@@ -35,6 +35,7 @@ Generally your Jest configuration should simply extend Heft's standard preset:
 
 ***Note:** If you find yourself frequently adding lots of custom settings to this file, please create a GitHub issue and tell us about it.  Our aim is to provide a configuration that minimizes the need for project-specific customizations.*
 
+
 ## package.json dependencies
 
 Heft has direct dependencies on the Jest packages that it needs, so you don't need to add Jest to your project's **package.json** file.

pages/heft_tasks/tslint.md

@@ -18,6 +18,7 @@ New projects should use the [eslint]({% link pages/heft_tasks/eslint.md %}) task
 
 There isn't a Heft-specific file for this task.  Heft looks for TSLint's config file [tslint.json](https://palantir.github.io/tslint/usage/configuration/).
 
+
 ## package.json dependencies
 
 None -- Heft loads the `tslint` package from the `@microsoft/rush-stack-compiler-*` bundle.  See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details.

pages/heft_tasks/typescript.md

@@ -50,6 +50,7 @@ To use this system, your **tsconfig.json** file should extend from one of the `i
 
 For advanced scenarios, Heft also provides an optional [typescript.json]({% link pages/heft_configs/typescript_json.md %}) config file that can be used to configure toolchain features such as multiple emit targets for the TypeScript compiler.
 
+
 ## package.json dependencies
 
 Heft itself does not require your project to depend on the `typescript` NPM package.  Instead, the TypeScript task will follow the `"extends"` references from **tsconfig.json**, and then call `require("typescript")` from that folder (**<project folder>/node_modules/@microsoft/rush-stack-compiler-3.9/** in the above example).  This reduces **package.json** boilerplate in a large monorepo.

pages/heft_tasks/webpack.md

@@ -59,6 +59,7 @@ module.exports = {
 };
 ```
 
+
 ## package.json dependencies
 
 None -- Heft loads the `@microsoft/api-extractor` package from the `@microsoft/rush-stack-compiler-*` bundle.  See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details.