| @@ -4,121 +4,59 @@ | ||
| 4 | 4 | ## Development Environment |
| 5 | 5 | |
| 6 | 6 | Stream uses [npm](https://npmjs.com) for javascript dependencies, [Composer](https://getcomposer.org) for PHP dependencies and the [Grunt](https://gruntjs.com) task runner to minimize and compile scripts and styles and to deploy to the WordPress.org plugin repository. |
| 7 | 7 | |
| 8 | -Included is a local development environment built with [Docker](https://www.docker.com). | |
| 8 | +Included is a local development environment built with [Docker](https://www.docker.com) which can be optionally run inside [Vagrant](https://www.vagrantup.com) for network isolation and better performance. | |
| 9 | 9 | |
| 10 | 10 | ### Requirements |
| 11 | 11 | |
| 12 | +- [VirtualBox](https://www.virtualbox.org) | |
| 13 | +- [Vagrant](https://www.vagrantup.com) | |
| 12 | 14 | - [Node.js](https://nodejs.org) |
| 13 | 15 | - [Composer](https://getcomposer.org) |
| 14 | 16 | |
| 15 | 17 | We suggest using the [Homebrew package manager](https://brew.sh) on macOS to install the dependencies: |
| 16 | 18 | |
| 17 | - brew install node@20 composer | |
| 18 | - brew install --cask docker | |
| 19 | + brew install node composer | |
| 20 | + brew cask install virtualbox vagrant | |
| 19 | 21 | |
| 22 | +For setups with local Docker environment you don't need Vagrant and VirtualBox. | |
| 23 | + | |
| 20 | 24 | ### Environment Setup |
| 21 | 25 | |
| 22 | 26 | 1. See the [Git Flow](#git-flow) section below for how to fork the repository. |
| 23 | -2. Run `npm install` and `composer install` to setup all project dependencies. | |
| 24 | -3. Run `npm build` to build the assets. | |
| 25 | -3. Run `npm start` to start the development environment. | |
| 26 | -4. Run `npm run install-wordpress` to set up the WordPress multisite network. | |
| 27 | -5. Visit [stream.wpenv.net](https://stream.wpenv.net) and login using `admin` / `password`. The dev environment forces HTTPS; if you haven't run `mkcert -install` on your host yet (see the HTTPS section below), your browser will show a "not secure" warning that you can dismiss. | |
| 28 | -6. Activate the Stream plugin. | |
| 27 | +2. Run `npm install` to install all project dependencies. | |
| 28 | +3. Run `vagrant up` to start the development environment. | |
| 29 | +4. Visit [stream.local](http://stream.local) and login using `admin` / `password`. | |
| 30 | +5. Activate the Stream plugin. | |
| 29 | 31 | |
| 30 | -### HTTPS for the dev environment | |
| 31 | - | |
| 32 | -The development environment also serves the site over HTTPS at https://stream.wpenv.net. HTTPS is required for testing WordPress Application Passwords and the Abilities API + MCP integration. | |
| 33 | - | |
| 34 | -Cert generation runs in a dedicated `mkcert` Docker service (defined in `docker-compose.yml`), so no host-side mkcert install is needed to **generate** the cert. The `mkcert` container runs once at `npm start`, writes `local/certs/cert.pem` and `local/certs/key.pem` (gitignored), and exits. The WordPress container picks them up via the SSL Apache vhost. | |
| 35 | - | |
| 36 | -To make the browser **trust** the locally-issued cert without a security warning, install the mkcert local CA in your host trust store once (this part still happens on the host because it needs access to the keychain / NSS DB): | |
| 37 | - | |
| 38 | -- macOS: `brew install mkcert nss && mkcert -install` | |
| 39 | -- Linux: install mkcert via your package manager, then `mkcert -install` | |
| 40 | -- Windows: `choco install mkcert && mkcert -install` | |
| 41 | - | |
| 42 | -If you skip the trust-store step, HTTPS still works; the browser just shows a "not secure" warning you can dismiss. Tools that don't perform cert validation (curl with `-k`, Playwright with `ignoreHTTPSErrors: true`, most MCP clients via app-password auth) are unaffected. | |
| 43 | - | |
| 44 | -Once the cert is generated and (optionally) trusted, visit https://stream.wpenv.net. | |
| 45 | - | |
| 46 | -**Existing environments** (set up before HTTPS was forced) still have `http://stream.wpenv.net` in their database. Upgrade with: | |
| 47 | - | |
| 48 | -```sh | |
| 49 | -docker compose run --rm --user $(id -u) wordpress -- \ | |
| 50 | - wp search-replace 'http://stream.wpenv.net' 'https://stream.wpenv.net' \ | |
| 51 | - --network --skip-columns=guid --report-changed-only | |
| 52 | -``` | |
| 53 | - | |
| 54 | -New `npm run install-wordpress` runs use the HTTPS URL from `local/public/wp-cli.yml` and don't need this step. | |
| 55 | - | |
| 56 | -### MCP (Model Context Protocol) integration | |
| 57 | - | |
| 58 | -Stream exposes its abilities as MCP-discoverable tools by tagging each registered ability with `meta.mcp.public = true`. The [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter) does the actual MCP server work; Stream does not load or initialize the adapter itself. | |
| 59 | - | |
| 60 | -The MCP Adapter is a `require-dev` Composer dependency declared as `"type": "wordpress-plugin"`, so `composer install` automatically drops it into `local/public/wp-content/plugins/mcp-adapter/`. You just need to activate it: | |
| 61 | - | |
| 62 | -```sh | |
| 63 | -docker compose run --rm --user $(id -u) wordpress -- wp plugin activate mcp-adapter --network | |
| 64 | -``` | |
| 65 | - | |
| 66 | -Then enable the "Enable Abilities API and MCP" toggle in Stream → Settings → Advanced (network admin on network-activated multisite). Verify the MCP default server route responds: | |
| 67 | - | |
| 68 | -```sh | |
| 69 | -curl -sk https://stream.wpenv.net/wp-json/mcp/mcp-adapter-default-server | |
| 70 | -``` | |
| 71 | - | |
| 72 | -To use MCP from Claude Desktop or another MCP client, follow the [mcp-adapter README's MCP client configuration section](https://github.com/WordPress/mcp-adapter#mcp-client-configuration). The HTTP transport requires the HTTPS setup above plus a WordPress Application Password. | |
| 73 | - | |
| 74 | 32 | ### PHP Xdebug |
| 75 | 33 | |
| 76 | -The WordPress container includes the [Xdebug PHP extension](https://xdebug.org). It is configured in the [`php.ini`](./local/docker/wordpress/php.ini) file to work in the [develop, debug and coverage modes](https://xdebug.org/docs/step_debug#mode). | |
| 34 | +The WordPress container includes the [Xdebug PHP extension](https://xdebug.org). It is configured to [autostart](https://xdebug.org/docs/remote#remote_autostart) and to [automatically detect the IP address of the connecting client](https://xdebug.org/docs/remote#remote_connect_back) running in your code editor. See [`.vscode/launch.json`](.vscode/launch.json) for the directory mapping from the WordPress container to the project directory in your code editor. | |
| 77 | 35 | |
| 78 | -[Step Debugging](https://xdebug.org/docs/step_debug) should work out of the box in VSCode thanks to the configuration file, [`.vscode/launch.json`](.vscode/launch.json). It contains the directory mapping from the WordPress container to the project directory in your code editor. | |
| 79 | - | |
| 80 | -In order to set up Step Debugging in PhpStorm, follow the [official guide](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html). Make sure to set up the same directory mappings as defined for VSCode in [`.vscode/launch.json`](.vscode/launch.json), e.g.: | |
| 81 | -- `${workspaceRoot}` -> `/var/www/html/wp-content/plugins/stream-src`, | |
| 82 | -- `${workspaceRoot}/build` -> `/var/www/html/wp-content/plugins/stream`, | |
| 83 | -- `${workspaceRoot}/local/public` -> `/var/www/html` | |
| 84 | - | |
| 85 | 36 | ### Mail Catcher |
| 86 | 37 | |
| 87 | -We use a [MailHog](https://github.com/mailhog/MailHog) container to capture all emails sent by the WordPress container, available at [stream.wpenv.net:8025](https://stream.wpenv.net:8025). | |
| 38 | +We use a [MailHog](https://github.com/mailhog/MailHog) container to capture all emails sent by the WordPress container, available at [stream.local:8025](https://stream.local:8025). | |
| 88 | 39 | |
| 89 | -### phpMyAdmin | |
| 90 | - | |
| 91 | -[phpMyAdmin ](https://www.phpmyadmin.net/) is available at [stream.wpenv.net:8080](http://stream.wpenv.net:8080/). | |
| 92 | - | |
| 93 | 40 | ### Scripts and Commands |
| 94 | 41 | |
| 95 | 42 | We use npm as the canonical task runner for the project. The following commands are available: |
| 96 | 43 | |
| 97 | -- `npm run start` to start the project's Docker containers. | |
| 98 | -- `npm run stop` to stop the project's Docker containers. | |
| 99 | -- `npm run stop-all` to stop _all_ Docker containers. | |
| 100 | 44 | - `npm run build` to build the plugin JS and CSS files. |
| 101 | -- `npm run dev` to watch and build the plugin assets continuously. | |
| 45 | + | |
| 102 | 46 | - `npm run lint` to check JS and PHP files for syntax and style issues. |
| 47 | + | |
| 103 | 48 | - `npm run deploy` to deploy the plugin to the WordPress.org repository. |
| 49 | + | |
| 104 | 50 | - `npm run cli -- wp info` where `wp info` is the CLI command to run inside the WordPress container. For example, use `npm run cli -- ls -lah` to list all files in the root of the WordPress installation. |
| 105 | -- `npm run test` to run PHPunit tests inside the WordPress container. | |
| 106 | -- `npm run test-xdebug` will run the PHPunit tests with Xdebug enabled. | |
| 107 | -- `npm run test-e2e` will run the Playwright E2E tests. | |
| 108 | -- `npm run test-e2e-debug` will run the Playwright E2E tests in a debug mode (with Chromium browser and dev tools open). | |
| 109 | -- `npm run switch-to:php7.4` and `npm run switch-to:php8.2` will switch you to either PHP 7.4 or PHP 8.2 | |
| 110 | -- `npm run document:connectors` generates [connectors.md](connectors.md). This runs via your local php. | |
| 111 | -- `npm run large-records-generate` inserts ~1.6M rows to `wp_stream` and ~8.4M rows to `wp_streammeta` for testing | |
| 112 | -- `npm run large-records-remove` removes the test data only | |
| 113 | -- `npm run large-records-show` shows how much test data is in the tables, this does not include non-test entries | |
| 114 | 51 | |
| 115 | -By default, tests have `WP_DEBUG` as false. You can override this if necessary by setting `WP_STREAM_TEST_DEBUG` to "yes". | |
| 52 | +- `npm run compose -- up -d` where `up -d` is the `docker-compose` command for the WordPress container. For example, use `npm run compose -- down` and `npm run compose -- up -d` to restart the WordPres container. | |
| 116 | 53 | |
| 117 | -### Docker issues | |
| 54 | +- `npm run phpunit` to run PHPunit tests inside the WordPress container. | |
| 118 | 55 | |
| 119 | -If you are having issues with incorrect versions of Xdebug or other Docker issues, first try rebuilding with no cache and up to date images using the command `docker compose build --no-cache --pull`. Then run `npm run start` as normal. | |
| 56 | +All `npm` commands running inside Vagrant are prefixed with `v`, for example, `npm run vcli` and `npm run vcompose`. | |
| 120 | 57 | |
| 58 | + | |
| 121 | 59 | ## Issues Tracker |
| 122 | 60 | |
| 123 | 61 | Support issues or usage questions should be posted on the [Plugin Support Forum](https://wordpress.org/support/plugin/stream). |
| 124 | 62 | |
| @@ -222,53 +160,4 @@ | ||
| 222 | 160 | |
| 223 | 161 | 7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) (with a clear title and description) to the `develop` branch. |
| 224 | 162 | |
| 225 | 163 | **IMPORTANT**: By submitting a patch, you agree to allow the project owner to license your work under the [GPL v2 license](https://www.gnu.org/licenses/gpl-2.0.html). |
| 226 | - | |
| 227 | -## Release Cycle | |
| 228 | - | |
| 229 | -The plugin versioning follows [semantic versioning](https://semver.org). | |
| 230 | - | |
| 231 | -### Pre-release | |
| 232 | - | |
| 233 | -Features, bug fixes, and other changes are assigned to a milestone. Once all issues in a milestone are closed: | |
| 234 | - | |
| 235 | -1. **Create Release Branch:** | |
| 236 | - - Branch off from `develop`. | |
| 237 | - - Name it `release/vX.Y.Z`, where `X.Y.Z` is the version number. | |
| 238 | - | |
| 239 | -2. **Update Metadata:** | |
| 240 | - - Update the plugin version, changelog and other relevant information. | |
| 241 | - | |
| 242 | -3. **Create Pre-release in GitHub:** | |
| 243 | - - Name the release like `X.Y.Z-rc.N`, e.g. `4.0.1-rc.1`. | |
| 244 | - - The tag name should be prefixed with `v`, e.g. `v4.0.1-rc.1`. | |
| 245 | - | |
| 246 | -4. **Review and Test:** | |
| 247 | - - Publishing a pre-release will trigger a GitHub action. | |
| 248 | - - A dry-run of WP.org deployment will occur (no files are committed). | |
| 249 | - - Review the SVN changes log in the action output. | |
| 250 | - - A ZIP archive with the plugin is created and uploaded as a release asset. | |
| 251 | - - Use that ZIP file for final testing. | |
| 252 | - | |
| 253 | -5. **Fix Issues:** | |
| 254 | - - If any issues are found, fix them in the release branch. | |
| 255 | - - Repeat the process from step 3. | |
| 256 | - | |
| 257 | -### Release | |
| 258 | - | |
| 259 | -Once ready, follow these steps: | |
| 260 | - | |
| 261 | -1. **Create Release in GitHub:** | |
| 262 | - - Name the release like `X.Y.Z`, e.g. `4.0.1`. | |
| 263 | - - The tag name should be prefixed with `v`, e.g. `v4.0.1`. | |
| 264 | - | |
| 265 | -2. **Confirm Deployment:** | |
| 266 | - - The GitHub action deploys the plugin to WP.org. | |
| 267 | - - Confirm the changes have been deployed to SVN in the [plugin trac](https://plugins.trac.wordpress.org/browser/stream/). | |
| 268 | - - A ZIP archive is created and uploaded to GitHub release assets. | |
| 269 | - | |
| 270 | -3. **Merge Branches:** | |
| 271 | - - Merge the release branch into `master`. | |
| 272 | - - Merge `master` into `develop`. | |
| 273 | - | |
| 274 | -By following this process, you ensure a smooth and consistent release cycle. | |
