Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 24 additions & 17 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,14 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ ├── .codecov.yml # Codecov configuration for test coverage reporting.
│ └── dependabot.yml # Dependabot configuration for automated dependency updates.
│
├── assets/ # Static assets that do not need compiling.
├── assets/ # Sources that webpack compiles into build/.
│ └── src/
│ ├── admin/
│ │ ├── search/ # Indices and Search settings.
│ │ └── settings/ # Plugin settings.
│ ├── components/
│ │ ├── AlgoliaSettings.tsx
│ │ ├── deactivation-settings.tsx
│ │ ├── IndexSummary.tsx # Which of a site's posts are in search.
│ │ ├── JobStatus.tsx # A background job that's queued, running or failed.
│ │ ├── MultiSelectChips.tsx
Expand All @@ -67,9 +68,12 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ ├── css/
│ │ └── admin.scss
│ ├── images/
│ └── js/
│ ├── use-index-status.ts # Loads the index summaries and jobs, and checks on them while jobs run.
│ └── utils.ts
│ │ └── logo.svg # The admin menu icon
│ ├── js/
│ │ ├── use-index-status.ts # Loads the index summaries and jobs, and checks on them while jobs run.
│ │ └── utils.ts
│ └── types/
│ └── global.d.ts
│
├── build/ # Compiled JS/CSS assets (generated by webpack.config.js).
│
Expand All @@ -78,7 +82,9 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ ├── CODE_OF_CONDUCT.md
│ ├── CONTRIBUTING.md
│ ├── DEVELOPMENT.md # 👈 You are here.
│ └── SECURITY.md
│ ├── SECURITY.md
│ └── guides/
│ └── setup.md
│
│ # PHP source files (plugin-specific code).
├── inc/
Expand All @@ -98,8 +104,9 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ │ └── Queue.php
│ ├── Modules/
│ │ ├── Core/
│ │ │ └── Assets.php # JS/CSS asset loader.
│ │ ├── Rest/ # One controller per route prefix.
│ │ │ ├── Assets.php # JS/CSS asset loader.
│ │ │ └── Uninstaller.php # Deletes the plugin's data on uninstall, or on deactivation if the site opted in.
│ │ ├── Rest/
│ │ │ ├── Abstract_REST_Controller.php
│ │ │ ├── Algolia_Credentials_Controller.php
│ │ │ ├── Brand_Site_Controller.php
Expand Down Expand Up @@ -143,8 +150,10 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ │ # Vitest unit tests.
│ ├── js/
│ │ └── tsconfig.json # Test TypeScript config.
│ │ # PHPStan stubs.
│ ├── phpstan/
│ │ # PHPUnit tests.
│ └── php/
│ └── phpunit/
│ ├── Integration/ # Integration tests.
│ ├── bootstrap.php # PHPUnit bootstrapper.
│ └── TestCase.php # Base test case class.
Expand All @@ -160,8 +169,6 @@ Code contributions, bug reports, and feature requests are welcome! The following
│ # .dist suffixes mean there may be a user-customized version without the suffix.
├── .browserslistrc # Browserslist configuration.
├── .editorconfig # Editor configuration.
├── .eslintignore # ESLint ignore patterns.
├── .eslintrc.js # ESLint configuration.
├── .gitignore # Git ignore rules.
├── .gitattributes # Git attributes.
├── .lefthook.yml # Git hooks configuration.
Expand All @@ -178,13 +185,13 @@ Code contributions, bug reports, and feature requests are welcome! The following
├── blueprint.json # WordPress Playground blueprint configuration.
├── babel.config.js # Babel configuration.
├── composer.json # PHP dependencies.
├── eslint.config.mjs # ESLint configuration.
├── LICENSE.md # License file.
├── package.json # Node.js dependencies.
├── playwright.config.ts # Playwright configuration.
├── phpstan.neon.dist # PHPStan configuration.
├── phpunit.xml.dist # PHPUnit configuration.
├── release-please-config.json # Release Please configuration.
├── .release-please-manifest.json # Release Please manifest file.
├── tsconfig.base.json # TypeScript base configuration.
├── tsconfig.json # TypeScript configuration.
├── vitest.config.mjs # Vitest configuration.
Expand Down Expand Up @@ -309,7 +316,7 @@ For more information on using `wp-env`, see the [wp-env documentation](https://d

- `npm run start:js`: Starts the JS/CSS watcher (development mode).
- `npm run build:dev`: Builds assets for development.
- `npm run build:prod`: Builds assets for production and installs optimized PHP dependencies.
- `npm run build:prod`: Cleans `build/` and builds assets for production.
- `npm run clean`: Cleans generated assets.

## Code Contributions (Pull Requests)
Expand All @@ -330,7 +337,7 @@ This project uses several tools to ensure code quality and standards are maintai

This project uses [ESLint](https://eslint.org) through `@wordpress/scripts` and `@wordpress/eslint-plugin` for JavaScript linting, following WordPress coding standards and best practices.

Our specific ESLint configuration is defined in the [`.eslintrc.js`](../.eslintrc.js) file.
Our specific ESLint configuration is defined in the [`eslint.config.mjs`](../eslint.config.mjs) file.

You can run ESLint on JavaScript files using:

Expand Down Expand Up @@ -424,7 +431,7 @@ By default, lefthook calls [lint-staged](https://github.com/okonet/lint-staged)

The project uses WordPress Playground to demo the plugin and on pull requests. The [`blueprint.json`](https://wordpress.github.io/wordpress-playground/blueprints) file enables testing and demos in the [WordPress Playground](https://playground.wordpress.net/).

The [README.md](../README.md) and plugin preview use [`blueprint.json`](../blueprint.json) to load the latest plugin release for testing and demos.
The plugin preview uses [`blueprint.json`](../blueprint.json) to load the latest plugin release for testing and demos.

Pull requests automatically generate a Playground preview from the build artifacts of the PR branch, using the [PR preview workflow](../.github/workflows/wp-playground-pr-preview.yml).

Expand All @@ -449,7 +456,7 @@ npm run test:php
To generate a code coverage report, make sure to start the testing environment with coverage mode enabled:

```bash
npm run wp-env start -- --xdebug-mode=coverage
npm run wp-env:test start -- --xdebug=coverage

npm run test:php
```
Expand Down Expand Up @@ -537,10 +544,10 @@ Releases are automated with [Release Please](https://github.com/googleapis/relea

1. Merge pull requests into `main` with **squash merge** and a Conventional Commit title.
2. Release Please updates and maintains a release PR from `main` using:
- [`.github/workflows/release-please.yml`](../.github/workflows/release-please.yml)
- [`.github/workflows/release.yml`](../.github/workflows/release.yml)
- [`release-please-config.json`](../release-please-config.json)
- [`.release-please-manifest.json`](../.release-please-manifest.json)
3. Merge the release PR when you're ready to ship.
4. Release Please creates the GitHub Release, which then triggers the [release workflow](../.github/workflows/release.yml) to build and upload the plugin zip asset.
4. Release Please creates the GitHub Release, and the same workflow then builds the plugin zip and uploads it to the release.

> **Note:** In `readme.txt` the Release Please markers are written as `<!-- x-release-please-start-version: -->` (with a colon). The WordPress.org readme parser stops reading the header at the first line without a colon, so a plain HTML comment would hide `Stable tag`, `Requires PHP` and `License`. With the colon the line is parsed as an unknown header key and ignored, and Release Please still matches the marker text.
Loading