diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7ab10b14 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,325 @@ +# Contributing to Harbor + +## Quick Start + +```bash +# JavaScript dependencies +bun install + +# PHP dependencies — --no-dev is sufficient for building assets and partner plugin testing. +# For running PHP tests or static analysis, see the PHP section below. +composer install --no-dev + +# Build React assets (required before testing in a partner plugin) +npm run build +``` + +All available scripts are listed in the [Scripts reference](#scripts-reference) below. + +--- + +## Prerequisites + +| Tool | Minimum version | Notes | +|---|---|---| +| [Bun](https://bun.sh) | **1.3.x** | Versions before 1.3.x may not install platform-specific native binary packages (e.g. `lightningcss-linux-x64-gnu`) correctly — `npm run build` will fail with a `Cannot find module` error. Confirmed working on 1.3.14. Run `bun --version` and update if needed: `curl -fsSL https://bun.sh/install \| bash` | +| Node.js | 14+ | Managed by `nvm` or included with Bun. `wp-scripts` requires Node 14+ for optional chaining syntax | +| Composer | 2.x | For PHP dependency management | +| PHP | 7.4+ | Required for Composer scripts and static analysis | + +--- + +## Installing Dependencies + +### JavaScript + +```bash +bun install +``` + +> **Bun version requirement:** Some Bun versions before 1.3.x silently skip optional packages +> that declare `os`/`cpu`/`libc` fields (e.g. `lightningcss-linux-x64-gnu`). The build will +> then fail when `postcss-loader` tries to load `lightningcss`. Confirmed working on 1.3.14. +> Update Bun before running `bun install`: `curl -fsSL https://bun.sh/install | bash`. + +### PHP + +Use `--no-dev` when your goal is **building assets or testing Harbor changes in a partner +plugin**. The dev dependency tree includes tools only needed for running the PHP test suite +itself (Codeception, PHPStan, phpcs) — none of which are required for the local partner +plugin workflow. + +```bash +# Building assets or testing via a partner plugin — use this +composer install --no-dev +``` + +Use the full install when you need to **run PHP tests or static analysis** locally: + +```bash +# PHP tests (Codeception/slic) or static analysis — use this +composer install +``` + +> **Known issue with full `composer install`:** The `lucatume/tdd-helpers` repository (a +> transitive dev dependency of `lucatume/wp-browser`) no longer exists on GitHub, causing +> the install to fail. PHP tests are typically run via [`slic`](https://github.com/stellarwp/slic), +> which manages its own container environment and is not affected by this issue. See +> [docs/guides/testing.md](docs/guides/testing.md) for the recommended test workflow. + +--- + +## Scripts Reference + +### JavaScript (`npm run