docs: add ProgressPlugin + progress reporting

Author: Spencer Elliott

src/content/api/plugins.md

@@ -99,6 +99,38 @@ compiler.hooks.myCustomHook.call(a, b, c);
 Again, see the [documentation](https://github.com/webpack/tapable) for `tapable` to learn more about the
 different hook classes and how they work.
 
+## Reporting Progress
+
+Plugins can report progress via [`ProgressPlugin`](/plugins/progress-plugin/), which prints progress messages to stderr by default. In order to enable progress reporting, pass a `--progress` argument when running the [webpack CLI](/api/cli/).
+
+It is possible to customize the printed output by passing different arguments to the `reportProgress` function of [`ProgressPlugin`](/plugins/progress-plugin/).
+
+To report progress, a plugin must `tap` into a hook using the `context: true` option:
+
+```js
+compiler.hooks.emit.tapAsync({
+  name: 'MyPlugin',
+  context: true
+}, (context, compiler, callback) => {
+  const reportProgress = context && context.reportProgress;
+  if (reportProgress) reportProgress(0.95, 'Starting work');
+  setTimeout(() => {
+    if (reportProgress) reportProgress(0.95, 'Done work');
+    callback();
+  }, 1000);
+});
+```
+
+The `reportProgress` function may be called with these arguments:
+
+```js
+reportProgress(percentage, ...args);
+```
+
+* `percentage`: This argument is unused; instead, [`ProgressPlugin`](/plugins/progress-plugin/) will calculate a percentage based on the current hook.
+* `...args`: Any number of strings, which will be passed to the `ProgressPlugin` handler to be reported to the user.
+
+Note that only a subset of compiler and compilation hooks support the `reportProgress` function. See [`ProgressPlugin`](/plugins/progress-plugin/#supported-hooks) for a full list.
 
 ## Next Steps
 

src/content/plugins/index.md

@@ -34,6 +34,7 @@ Name                                                     | Description
 [`NoEmitOnErrorsPlugin`](/configuration/optimization/#optimization-noemitonerrors)  | Skip the emitting phase when there are compilation errors
 [`NormalModuleReplacementPlugin`](/plugins/normal-module-replacement-plugin) | Replace resource(s) that matches a regexp
 [`NpmInstallWebpackPlugin`](/plugins/npm-install-webpack-plugin) | Auto-install missing dependencies during development
+[`ProgressPlugin`](/plugins/progress-plugin)                     | Report compilation progress
 [`ProvidePlugin`](/plugins/provide-plugin)                       | Use modules without having to use import/require
 [`SourceMapDevToolPlugin`](/plugins/source-map-dev-tool-plugin)  | Enables a more fine grained control of source maps
 [`EvalSourceMapDevToolPlugin`](/plugins/eval-source-map-dev-tool-plugin)  | Enables a more fine grained control of eval source maps

src/content/plugins/progress-plugin.md

@@ -0,0 +1,98 @@
+---
+title: ProgressPlugin
+contributors:
+  - elliottsj
+---
+
+The `ProgressPlugin` provides a way to customize how progress is reported during a compilation.
+
+## Usage
+
+Create an instance of `ProgressPlugin` with a handler function which will be called when hooks report progress:
+
+```js
+const handler = (percentage, message, ...args) => {
+  // e.g. Output each progress message directly to the console:
+  console.info(percentage, message, ...args);
+};
+
+new webpack.ProgressPlugin(handler);
+```
+
+* `handler` is a function which takes these arguments:
+  * `percentage`: a number between 0 and 1 indicating the completion percentage of the compilation.
+  * `message`: a short description of the currently-executing hook.
+  * `...args`: zero or more additional strings describing the current progress.
+
+## Supported Hooks
+
+The following hooks report progress information to `ProgressPlugin`.
+
+T> _Hooks marked with * allow plugins to report progress information using `reportProgress`. For more, see [Plugin API: Reporting Progress](/api/plugins/#reporting-progress)_
+
+**Compiler**
+
+* compilation
+* emit*
+* afterEmit*
+* done
+
+**Compilation**
+
+* buildModule
+* failedModule
+* succeedModule
+* finishModules*
+* seal*
+* optimizeDependenciesBasic*
+* optimizeDependencies*
+* optimizeDependenciesAdvanced*
+* afterOptimizeDependencies*
+* optimize*
+* optimizeModulesBasic*
+* optimizeModules*
+* optimizeModulesAdvanced*
+* afterOptimizeModules*
+* optimizeChunksBasic*
+* optimizeChunks*
+* optimizeChunksAdvanced*
+* afterOptimizeChunks*
+* optimizeTree*
+* afterOptimizeTree*
+* optimizeChunkModulesBasic*
+* optimizeChunkModules*
+* optimizeChunkModulesAdvanced*
+* afterOptimizeChunkModules*
+* reviveModules*
+* optimizeModuleOrder*
+* advancedOptimizeModuleOrder*
+* beforeModuleIds*
+* moduleIds*
+* optimizeModuleIds*
+* afterOptimizeModuleIds*
+* reviveChunks*
+* optimizeChunkOrder*
+* beforeChunkIds*
+* optimizeChunkIds*
+* afterOptimizeChunkIds*
+* recordModules*
+* recordChunks*
+* beforeHash*
+* afterHash*
+* recordHash*
+* beforeModuleAssets*
+* beforeChunkAssets*
+* additionalChunkAssets*
+* record*
+* additionalAssets*
+* optimizeChunkAssets*
+* afterOptimizeChunkAssets*
+* optimizeAssets*
+* afterOptimizeAssets*
+* afterSeal*
+
+## References
+
+### Source
+
+* [`ProgressPlugin` source](https://github.com/webpack/webpack/blob/master/lib/ProgressPlugin.js)