diff --git a/.gitignore b/.gitignore index 96f49190bf8b53..fc31278c325ded 100644 --- 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 index 098ffa7f5f468b..30f424ed2cbb90 100644 --- 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 index 71abc3fa61e017..893e165daeb7c3 100644 --- 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 | `.|~` | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` | -| Absolute path | `/|:\` | `"/a/directory"`, `"C:\\a\\directory"` | -| GitHub repository | `/[#]` | `"WordPress/WordPress"`, `"WordPress/gutenberg#master"` | +| Type | Format | Example(s) | +| ----------------- | -------------------------- | -------------------------------------------------------- | +| Relative path | `.|~` | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` | +| Absolute path | `/|:\` | `"/a/directory"`, `"C:\\a\\directory"` | +| GitHub repository | `/[#]` | `"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 index 320d38ab0730fe..3ef4c93291f3d9 100644 --- a/packages/env/lib/config.js +++ b/packages/env/lib/config.js @@ -61,6 +61,7 @@ module.exports = { const configDirectoryPath = path.dirname( configPath ); let config = null; + let overrideConfig = {}; try { config = JSON.parse( await fs.readFile( configPath, 'utf8' ) ); @@ -78,6 +79,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' ) { @@ -101,7 +126,8 @@ module.exports = { port: 8888, testsPort: 8889, }, - config + config, + overrideConfig ); config.port = getNumberFromEnvVariable( 'WP_ENV_PORT' ) || config.port;