Merge pull request #1101 from pact-foundation/docs/v12_migration

docs: add notes on v12 migration/troubleshotting

MIGRATION.md

@@ -1,5 +1,13 @@
 # Pact-js migration guide
 
+# 11.x.x -> 12.x.x
+
+- Node versions less than 16 are no longer supported
+- Pact FFI library is now prebuilt and included in the distributable dropping the requirement for a node-gyp build chain. Users can now use `--ignore-scripts`
+  - If errors are seen finding the native library, please
+    - run with `LOG_LEVEL=debug`
+    - follow the instructions provided
+
 # 10.x.x -> 11.x.x
 
 There is just one single [breaking change](https://github.com/pact-foundation/pact-js/blob/master/CHANGELOG.md#-breaking-changes) in this release. A conflicting type `StateHandlers` has been renamed to  `MessageStateHandlers` for use in message pact tests.

README.md

@@ -99,8 +99,11 @@ Looking for the previous [stable 9.x.x release](https://github.com/pact-foundati
 
 ### Requirements
 
-1. Make sure the `ignore-scripts` option is disabled, pact uses npm scripts to compile native dependencies and won't function without it.
-2. Pact uses native extensions and installs them via the [`node-gyp`](https://github.com/nodejs/node-gyp) package. This requires a [build chain](https://github.com/nodejs/node-gyp#installation) for a successful installation. See also issue [#899](https://github.com/pact-foundation/pact-js/issues/899). 
+Node 16+ as of pact-js v12
+
+1. If using pact-js v11 or lower,
+   1. make sure the `ignore-scripts` option is disabled, pact uses npm scripts to compile native dependencies and won't function without it.
+   2. Pact uses native extensions and installs them via the [`node-gyp`](https://github.com/nodejs/node-gyp) package. This requires a [build chain](https://github.com/nodejs/node-gyp#installation) for a successful installation. See also issue [#899](https://github.com/pact-foundation/pact-js/issues/899). This is now prebuilt in pact-js v12+
 
 ### Do Not Track
 

docs/troubleshooting.md

@@ -209,7 +209,9 @@ The Jest [docs](https://jestjs.io/docs/asynchronous) explains why, but this prin
 
 ## Installation failing (Missing Python, C++ or build tools)
 
-Pact has the following requirements for a successful install:
+TL;DR - Upgrade to pact-js v12
+
+Pact-JS v10-v11 have the following requirements for a successful install:
 
 1. Make sure the `ignore-scripts` option is disabled, pact uses npm scripts to compile native dependencies and won't function without it.
 2. Pact uses native extensions and installs them via the [`node-gyp`](https://github.com/nodejs/node-gyp) package. This requires a [build chain](https://github.com/nodejs/node-gyp#installation) for a successful installation. See also issue [#899](https://github.com/pact-foundation/pact-js/issues/899).
@@ -285,6 +287,25 @@ npm ERR! gyp ERR! stack Error: Could not find any Visual Studio installation to
 ...
 ```
 
+## Failed to find native build
+
+Users can now use `--ignore-scripts`
+  - If errors are seen finding the native library, please
+    - run with `LOG_LEVEL=debug`
+    - follow the instructions provided
+      - You can override the path to the pact native build with `PACT_PREBUILD_LOCATION`
+
+
+## ENOENT: no such file or directory, open 'node:path'
+
+Pact-js-core uses `node:path`, this is supported by node 16+
+
+Some test frameworks may rely on older bindings, and you may see this error.
+
+Affected frameworks
+
+- Jest 26 and below. Upgrade to v27
+
 ## Why are there duplicate / extraneous interactions in my pact file?
 
 You must clear out the pacts directory prior to running your tests. Pact tests may be run in parallel, which makes it difficult for Pact to know when the file is safe to clear. This is usually not a problem unless you upload from your development environment, as in CI / automation contexts, it's less likely that you have previous test runs lying around.