Env: Add support for local override files. (#20341)

* Env: Add support for local override files. * Document
WordPress · Mar 2, 2020 · 013e035 · 013e035
1 parent 6beb836
commit 013e035
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 44 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,6 @@ playground/dist
 
 # Report generated from jest-junit
 test/native/junit.xml
+
+# Local overrides
+.wp-env.override.json
diff --git a/packages/env/CHANGELOG.md b/packages/env/CHANGELOG.md
@@ -2,22 +2,23 @@
 
 ### New Feature
 
-- You may now override the directory in which `wp-env` creates generated files with the `WP_ENV_HOME` environment variable. The default directory is `~/.wp-env/` (or `~/wp-env/` on Linux).
-- The `.wp-env.json` coniguration file now accepts `port` and `testsPort` options which can be used to set the ports on which the docker instance is mounted.
+-   A `.wp-env.override.json` configuration file can now be used to override fields from `.wp-env.json`.
+-   You may now override the directory in which `wp-env` creates generated files with the `WP_ENV_HOME` environment variable. The default directory is `~/.wp-env/` (or `~/wp-env/` on Linux).
+-   The `.wp-env.json` coniguration file now accepts `port` and `testsPort` options which can be used to set the ports on which the docker instance is mounted.
 
 ## 1.0.0 (2020-02-10)
 
 ### Breaking Changes
 
-- `wp-env start` no longer accepts a WordPress branch or tag reference as its argument. Instead, create a `.wp-env.json` file and specify a `"core"` field.
-- `wp-env start` will now download WordPress into a hidden directory located in `~/.wp-env`. You may delete your `{projectName}-wordpress` and `{projectName}-tests-wordpress` directories.
+-   `wp-env start` no longer accepts a WordPress branch or tag reference as its argument. Instead, create a `.wp-env.json` file and specify a `"core"` field.
+-   `wp-env start` will now download WordPress into a hidden directory located in `~/.wp-env`. You may delete your `{projectName}-wordpress` and `{projectName}-tests-wordpress` directories.
 
 ### New Feature
 
-- A `.wp-env.json` configuration file can now be used to specify the WordPress installation, plugins, and themes to use in the local development environment.
+-   A `.wp-env.json` configuration file can now be used to specify the WordPress installation, plugins, and themes to use in the local development environment.
 
 ## 0.4.0 (2020-02-04)
 
 ### Bug Fixes
 
-- When running scripts using `wp-env run`, the output will not be formatted if not written to terminal display, resolving an issue where piped or redirected output could be unintentionally padded with newlines.
+-   When running scripts using `wp-env run`, the output will not be formatted if not written to terminal display, resolving an issue where piped or redirected output could be unintentionally padded with newlines.
diff --git a/packages/env/README.md b/packages/env/README.md
@@ -181,26 +181,30 @@ You can customize the WordPress installation, plugins and themes that the develo
 
 `.wp-env.json` supports five fields:
 
-| Field | Type | Default | Description |
-| -- | -- | -- | -- |
-| `"core"` | `string|null` | `null` | The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress. |
-| `"plugins"` | `string[]` | `[]` | A list of plugins to install and activate in the environment. |
-| `"themes"` | `string[]` | `[]` | A list of themes to install in the environment. The first theme in the list will be activated. |
-| `"port"` | `string` | `"8888"` | The primary port number to use for the insallation. You'll access the instance through the port: 'http://localhost:8888'. |
-| `"testsPort"` | `string` | `"8889"` | The port number to use for the tests instance. |
+| Field         | Type          | Default  | Description                                                                                                               |
+| ------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `"core"`      | `string|null` | `null`   | The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress.  |
+| `"plugins"`   | `string[]`    | `[]`     | A list of plugins to install and activate in the environment.                                                             |
+| `"themes"`    | `string[]`    | `[]`     | A list of themes to install in the environment. The first theme in the list will be activated.                            |
+| `"port"`      | `string`      | `"8888"` | The primary port number to use for the insallation. You'll access the instance through the port: 'http://localhost:8888'. |
+| `"testsPort"` | `string`      | `"8889"` | The port number to use for the tests instance.                                                                            |
 
 _Note: the port number environment variables (`WP_ENV_PORT` and `WP_ENV_TESTS_PORT`) take precedent over the .wp-env.json values._
 
 Several types of strings can be passed into the `core`, `plugins`, and `themes` fields:
 
-| Type | Format | Example(s) |
-| -- | -- | -- |
-| Relative path | `.<path>|~<path>` | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` |
-| Absolute path | `/<path>|<letter>:\<path>` | `"/a/directory"`, `"C:\\a\\directory"` |
-| GitHub repository | `<owner>/<repo>[#<ref>]` | `"WordPress/WordPress"`, `"WordPress/gutenberg#master"` |
+| Type              | Format                     | Example(s)                                               |
+| ----------------- | -------------------------- | -------------------------------------------------------- |
+| Relative path     | `.<path>|~<path>`          | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` |
+| Absolute path     | `/<path>|<letter>:\<path>` | `"/a/directory"`, `"C:\\a\\directory"`                   |
+| GitHub repository | `<owner>/<repo>[#<ref>]`   | `"WordPress/WordPress"`, `"WordPress/gutenberg#master"`  |
 
 Remote sources will be downloaded into a temporary directory located in `~/.wp-env`.
 
+## .wp-env.override.json
+
+Any fields here will take precedence over .wp-env.json. This file is useful, when ignored from version control, to persist local development overrides.
+
 ### Examples
 
 #### Latest production WordPress + current directory as a plugin
@@ -209,10 +213,8 @@ This is useful for plugin development.
 
 ```json
 {
-  "core": null,
-  "plugins": [
-    "."
-  ]
+	"core": null,
+	"plugins": [ "." ]
 }
 ```
 
@@ -222,10 +224,8 @@ This is useful for plugin development when upstream Core changes need to be test
 
 ```json
 {
-  "core": "WordPress/WordPress#master",
-  "plugins": [
-    "."
-  ]
+	"core": "WordPress/WordPress#master",
+	"plugins": [ "." ]
 }
 ```
 
@@ -235,10 +235,8 @@ This is useful for working on plugins and WordPress Core at the same time.
 
 ```json
 {
-  "core": "../wordpress-develop/build",
-  "plugins": [
-    "."
-  ]
+	"core": "../wordpress-develop/build",
+	"plugins": [ "." ]
 }
 ```
 
@@ -248,14 +246,9 @@ This is useful for integration testing: that is, testing how old versions of Wor
 
 ```json
 {
-  "core": "WordPress/WordPress#5.2.0",
-  "plugins": [
-    "WordPress/wp-lazy-loading",
-    "WordPress/classic-editor",
-  ],
-  "themes": [
-    "WordPress/theme-experiments"
-  ]
+	"core": "WordPress/WordPress#5.2.0",
+	"plugins": [ "WordPress/wp-lazy-loading", "WordPress/classic-editor" ],
+	"themes": [ "WordPress/theme-experiments" ]
 }
 ```
 
@@ -265,11 +258,9 @@ You can tell `wp-env` to use a custom port number so that your instance does not
 
 ```json
 {
-  "plugins": [
-    ".",
-  ],
-  "port": 4013,
-  "testsPort": 4012
+	"plugins": [ "." ],
+	"port": 4013,
+	"testsPort": 4012
 }
 ```
 

diff --git a/packages/env/lib/config.js b/packages/env/lib/config.js
@@ -62,6 +62,7 @@ module.exports = {
 		const configDirectoryPath = path.dirname( configPath );
 
 		let config = null;
+		let overrideConfig = {};
 
 		try {
 			config = JSON.parse( await fs.readFile( configPath, 'utf8' ) );
@@ -79,6 +80,30 @@ module.exports = {
 			}
 		}
 
+		try {
+			overrideConfig = JSON.parse(
+				await fs.readFile(
+					configPath.replace(
+						/\.wp-env\.json$/,
+						'.wp-env.override.json'
+					),
+					'utf8'
+				)
+			);
+		} catch ( error ) {
+			if ( error.code === 'ENOENT' ) {
+				// Config override file does not exist. Do nothing - it's optional.
+			} else if ( error instanceof SyntaxError ) {
+				throw new ValidationError(
+					`Invalid .wp-env.override.json: ${ error.message }`
+				);
+			} else {
+				throw new ValidationError(
+					`Could not read .wp-env.override.json: ${ error.message }`
+				);
+			}
+		}
+
 		if ( config === null ) {
 			const type = await detectDirectoryType( configDirectoryPath );
 			if ( type === 'core' ) {
@@ -102,7 +127,8 @@ module.exports = {
 				port: 8888,
 				testsPort: 8889,
 			},
-			config
+			config,
+			overrideConfig
 		);
 
 		config.port = getNumberFromEnvVariable( 'WP_ENV_PORT' ) || config.port;