docs: UPGRADING.md for 8.0.0, some tweaks and tidy up CHANGELOG.md

CHANGELOG.md

@@ -13,15 +13,12 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 
 ## [8.0.0-rc.3] - 2022-03-21
 ### Added
+- Add support for Node.js 17
 - Cucumber Expressions now support a wider array of parameter types (see [documentation](https://github.com/cucumber/cucumber-expressions#parameter-types))
 - Improved styling and usability on report from `html` formatter
-- Support for customising work assignment when running in parallel ([#1044](https://github.com/cucumber/cucumber-js/issues/1044)
-[#1588](https://github.com/cucumber/cucumber-js/pull/1588))
-- Add a new option to `--format-options`: `printAttachments`.
-See [./docs/cli.md#printing-attachments-details](https://github.com/cucumber/cucumber-js/blob/main/docs/cli.md#printing-attachments-details) for more info.
-([#1136](https://github.com/cucumber/cucumber-js/issues/1136)
-[#1721](https://github.com/cucumber/cucumber-js/pull/1721))
-- Support for configuration to be objects instead of argv strings, and for configuration files in ESM and JSON formats ([#1952](https://github.com/cucumber/cucumber-js/pull/1952))
+- Support for customising work assignment when running in parallel (see [documentation](./docs/parallel.md#custom-work-assignment)) ([#1044](https://github.com/cucumber/cucumber-js/issues/1044) [#1588](https://github.com/cucumber/cucumber-js/pull/1588))
+- Add a new option to `--format-options`: `printAttachments` (see [documentation](./docs/cli.md#printing-attachments-details)) ([#1136](https://github.com/cucumber/cucumber-js/issues/1136) [#1721](https://github.com/cucumber/cucumber-js/pull/1721))
+- Support for configuration to be objects instead of argv strings, and for configuration files in ESM and JSON formats (see [documentation](./docs/configuration.md#files)) ([#1952](https://github.com/cucumber/cucumber-js/pull/1952))
 - New API for running Cucumber programmatically (see [documentation](./docs/javascript_api.md)) ([#1955](https://github.com/cucumber/cucumber-js/pull/1955))
 
 ### Changed
@@ -31,28 +28,23 @@ See [./docs/cli.md#printing-attachments-details](https://github.com/cucumber/cuc
 - `parseGherkinMessageStream` is deprecated in favour of `loadSources` ([#1957](https://github.com/cucumber/cucumber-js/pull/1957))
 
 ### Fixed
-- Warn users who are on an unsupported node version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922))
+- Warn users who are on an unsupported Node.js version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922))
 - Allow formatters to finish when a Gherkin parse error is encountered ([#1404](https://github.com/cucumber/cucumber-js/issues/1404) [#1951](https://github.com/cucumber/cucumber-js/pull/1951))
 
 ### Removed
-- `getConfiguration`, `initializeFormatters` and `getSupportCodeLibrary` methods removed from `Cli` class in favour of new API
+- `getConfiguration`, `initializeFormatters` and `getSupportCodeLibrary` methods removed from `Cli` class in favour of [new API](./docs/javascript_api.md)
 
 ## [8.0.0-rc.2] - 2022-01-10
 ### Added
-- Export cucumber version number. It is now possible to retrieve the current version
-of cucumber using `import { version } from '@cucumber/cucumber'`.
-([PR#1866](https://github.com/cucumber/cucumber-js/pull/1866)
-[Issue#1853](https://github.com/cucumber/cucumber-js/issues/1853))
+- Export Cucumber's version number. It is now possible to retrieve the current version of Cucumber using `import { version } from '@cucumber/cucumber'` ([#1866](https://github.com/cucumber/cucumber-js/pull/1866) [#1853](https://github.com/cucumber/cucumber-js/issues/1853))
 
 ### Changed
 - Switched to new `@cucumber/ci-environment` library for CI detection ([#1868](https://github.com/cucumber/cucumber-js/pull/1868))
 
 ### Fixed
-- Handles spaces in paths for developers working on cucumbers's own code ([#1845](https://github.com/cucumber/cucumber-js/issues/1845))
-- Ensure package.json can be imported by consuming projects
-([PR#1870](https://github.com/cucumber/cucumber-js/pull/1870)
-[Issue#1869](https://github.com/cucumber/cucumber-js/issues/1869))
-- Allows for parentheses in paths for developers working on cucumber's own code ([[#1735](https://github.com/cucumber/cucumber-js/issues/1735)])
+- Handles spaces in paths for developers working on Cucumber's own code ([#1845](https://github.com/cucumber/cucumber-js/issues/1845))
+- Ensure `package.json` can be imported by consuming projects ([#1870](https://github.com/cucumber/cucumber-js/pull/1870) [#1869](https://github.com/cucumber/cucumber-js/issues/1869))
+- Allows for parentheses in paths for developers working on Cucumber's own code ([#1735](https://github.com/cucumber/cucumber-js/issues/1735))
 - Smoother onboarding for Windows developers ([#1863](https://github.com/cucumber/cucumber-js/pull/1863))
 - Pin `colors` to `1.4.0` to fix security vulnerability ([#1884](https://github.com/cucumber/cucumber-js/issues/1884))
 - Pin `cli-table3` to `0.6.1` to fix security vulnerability ([#251](https://github.com/cli-table/cli-table3/pull/251))
@@ -61,22 +53,18 @@ of cucumber using `import { version } from '@cucumber/cucumber'`.
 ### Added
 - Add `wrapPromiseWithTimeout` to public API ([#1566](https://github.com/cucumber/cucumber-js/pull/1566))
 - Add support for user code as native ES modules
-- `BeforeStep` and `AfterStep` hook functions now have access to the `pickleStep` in their argument object.
-- `--config` option to the CLI. It allows you to specify a configuration file other than `cucumber.js`.
-See [docs/profiles.md](./docs/profiles.md#using-another-file-than-cucumberjs) for more info.
-[#1794](https://github.com/cucumber/cucumber-js/pull/1794)
+- `BeforeStep` and `AfterStep` hook functions now have access to the `pickleStep` in their argument object
+- `--config` option to the CLI. It allows you to specify a configuration file other than `cucumber.js` (see [documentation](./docs/profiles.md#using-another-file-than-cucumberjs)) [#1794](https://github.com/cucumber/cucumber-js/pull/1794)
 
 ### Changed
 - Relative paths for custom snippet syntaxes must begin with `.` ([#1640](https://github.com/cucumber/cucumber-js/issues/1640))
 - Absolute paths for custom formatters and snippet syntaxes must be a valid `file://` URL
-- Use performance timers for test case duration measurement.
-[#1793](https://github.com/cucumber/cucumber-js/pull/1793)
+- Use performance timers for test case duration measurement [#1793](https://github.com/cucumber/cucumber-js/pull/1793)
 
 ### Fixed
-- Allow targetting same file multiple times ([#1708](https://github.com/cucumber/cucumber-js/pull/1708))
-- When running with `--dry-run`, undefined or ambiguous steps no longer cause the process to exit with code 1. ([#1814](https://github.com/cucumber/cucumber-js/pull/1814))
-- When running the help command, it now shows all available formatters under the --format option.
-[#1798](https://github.com/cucumber/cucumber-js/pull/1798)
+- Allow targeting same file multiple times ([#1708](https://github.com/cucumber/cucumber-js/pull/1708))
+- When running with `--dry-run`, undefined or ambiguous steps no longer cause the process to exit with code 1 ([#1814](https://github.com/cucumber/cucumber-js/pull/1814))
+- When running the `--help` command, it now shows all available formatters under the `--format` option [#1798](https://github.com/cucumber/cucumber-js/pull/1798)
 
 ### Removed
 - Drop support for Node.js 10 and 15, add support for Node.js 16

docs/migration.md → UPGRADING.md

@@ -1,6 +1,10 @@
-# Migrating to cucumber-js 8.x.x
+# Upgrading
 
-## Generator step definitions
+This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](./CHANGELOG.md).
+
+## 8.0.0
+
+### Generator step definitions
 
 Generator functions used in step definitions (`function*` with the `yield` keyword)
 are not natively supported anymore with cucumber-js.
@@ -25,11 +29,40 @@ setDefinitionFunctionWrapper(function (fn) {
 })
 ```
 
-# Migrating to cucumber-js 7.x.x
+### Using `Cli` programmatically
+
+The `Cli` class is sometimes used to run Cucumber programmatically. We've had to make a few breaking changes:
+
+- `getConfiguration`, `initializeFormatters` and `getSupportCodeLibrary` methods are removed
+- The constructor object has two new required properties:
+  - `stderr` - writable stream to which we direct warning/error output - you might just pass `process.stderr`
+  - `env` - environment variables from which we detect some configuration options - you might just pass `process.env`
+
+In general for programmatic running (including those removed methods) we'd advise switching to [the new API](docs/javascript_api.md) which is designed for this purpose.
+
+### Deep requires
+
+Previously, you could `require` anything directly from Cucumber's internals e.g. `require('@cucumber/cucumber/lib/formatter/helpers')`. As part of adding ESM support we've added subpath exports, which restricts where Node.js can resolve modules from within the package. Deep requires are still possible but in a more limited way e.g. no implicit resolving of `/index.js` with the above example. In a future release we'll remove the capability for deep requires entirely, so we'd advise addressing any instances in your code (here's [an example](https://github.com/cucumber/cucumber-js-pretty-formatter/pull/11)). Everything you need should be available via the main entry point, but if something's missing please [raise an issue](https://github.com/cucumber/cucumber-js/issues).
+
+### Formatter and snippet paths
+
+When providing the path to a custom formatter or snippet syntax:
+
+- For relative paths, you now need to ensure it begins with a `.` (this was already the case for custom formatters as of 7.0.0; snippet syntaxes are being changed to match)
+- For absolute paths, you now need to provide it as a valid `file://` URL
+
+### CLI options
+
+These CLI options have been removed:
+
+- `--retryTagFilter` - the correct option is `--retry-tag-filter`
+- `--predictable-ids` - this was only used for internal testing
+
+## 7.0.0
 
-## Package Name
+### Package Name
 
-cucumber-js is now published at `@cucumber/cucumber` instead of `cucumber`. To upgrade, you'll need to remove the old package and add the new one:
+Cucumber is now published at `@cucumber/cucumber` instead of `cucumber`. To upgrade, you'll need to remove the old package and add the new one:
 
 ```shell
 $ npm rm cucumber
@@ -40,7 +73,7 @@ You'll need to update any `import`/`require` statements in your support code to
 
 (The executable is still `cucumber-js` though.)
 
-## Hooks
+### Hooks
 
 The result object passed as the argument to your `After` hook function has a different structure.
 
@@ -85,7 +118,7 @@ Now in `@cucumber/cucumber`:
 }
 ```
 
-## Formatters
+### Formatters
 
 The underlying event/data model for cucumber-js is now [cucumber-messages](https://github.com/cucumber/cucumber/tree/master/messages), a shared standard across all official Cucumber implementations. This replaces the old "event protocol".
 
@@ -99,18 +132,18 @@ $ cucumber-js --format @cucumber/pretty-formatter
 
 This does mean that if you want to point to a local formatter implementation (i.e. not a Node module) then you should ensure it's a relative path starting with `./`.
 
-## Parallel
+### Parallel
 
 The parallel mode previously used problematic "master"/"slave" naming that we've dropped in favour of "coordinator" and "worker". This is mostly an internal detail, but is also reflected in the names of some environment variables you might be using:
 
 * `CUCUMBER_TOTAL_SLAVES` is now `CUCUMBER_TOTAL_WORKERS`
 * `CUCUMBER_SLAVE_ID` is now `CUCUMBER_WORKER_ID`
 
-## TypeScript
+### TypeScript
 
 *(You can skip this part if you don't use TypeScript in your projects.)*
 
-Where before we relied on the community-authored `@types/cucumber` package, cucumber-js is now built with TypeScript and as such includes its own typings, so you can drop your dependency on the separate package:
+Where before we relied on the community-authored `@types/cucumber` package, Cucumber is now built with TypeScript and as such includes its own typings, so you can drop your dependency on the separate package:
 
 ```shell
 $ npm rm @types/cucumber
@@ -119,10 +152,10 @@ $ npm rm @types/cucumber
 There are a few minor differences to be aware of:
 
 - The type for data tables was named `TableDefinition` - it's now named `DataTable`
-- `World` was typed as an interface, but it's actually a class - you should `extend` it when [building a custom formatter](./custom_formatters.md)
+- `World` was typed as an interface, but it's actually a class - you should `extend` it when [building a custom formatter](docs/custom_formatters.md)
 
 Also, your `tsconfig.json` should have the `resolveJsonModule` compiler option switched on. Other than that, a pretty standard TypeScript setup should work as expected.
 
-## Timeouts
+### Timeouts
 
 You can no longer call `setDefaultTimeout` from within other support code e.g. a step, hook or your World class; it should be called globally.

docs/esm.md

@@ -4,7 +4,7 @@ You can optionally write your support code (steps, hooks, etc) with native ES mo
 
 If your support code is written as ESM, you'll need to use the `import` configuration option to specify your files, rather than the `require` option, although we do automatically detect and import any `.mjs` files found within your features directory.
 
-Example (adapted from [our original example](./nodejs_example.md)):
+Example:
 
 ```javascript
 // features/support/steps.mjs