| 1 |
# Edit Flow |
| 2 |
|
| 3 |
Editorial workflow plugin with custom statuses, editorial comments, and notifications. |
| 4 |
|
| 5 |
## Project Knowledge |
| 6 |
|
| 7 |
| Property | Value | |
| 8 |
|----------|-------| |
| 9 |
| **Main file** | `edit_flow.php` | |
| 10 |
| **Text domain** | `edit-flow` | |
| 11 |
| **Function prefix** | `ef_` | |
| 12 |
| **Namespace** | Global (legacy) | |
| 13 |
| **Source directory** | `modules/` | |
| 14 |
| **Version** | 0.11.0 | |
| 15 |
| **Requires PHP** | 7.4+ | |
| 16 |
| **Requires WP** | 6.4+ | |
| 17 |
|
| 18 |
### Directory Structure |
| 19 |
|
| 20 |
``` |
| 21 |
edit-flow/ |
| 22 |
├── edit_flow.php # Main plugin file (note: underscore in filename) |
| 23 |
├── edit-flow.php # Redirect file (hyphenated, loads the underscore version) |
| 24 |
├── common/ # Shared utilities and base module class |
| 25 |
├── modules/ # Feature modules (each is self-contained) |
| 26 |
│ ├── calendar/ # Editorial calendar |
| 27 |
│ ├── custom-status/ # Custom post statuses |
| 28 |
│ ├── dashboard/ # Dashboard widgets |
| 29 |
│ ├── editorial-comments/ # In-post editorial comments |
| 30 |
│ ├── editorial-metadata/ # Custom editorial fields |
| 31 |
│ ├── notifications/ # Email notifications |
| 32 |
│ ├── settings/ # Plugin settings |
| 33 |
│ ├── story-budget/ # Story budget overview |
| 34 |
│ └── user-groups/ # User group management |
| 35 |
├── tests/ # Integration tests |
| 36 |
├── build/ # Built assets |
| 37 |
├── dist/ # Distribution assets |
| 38 |
├── .github/workflows/ # CI: deploy, e2e-tests, integration, js-tests, php-lint |
| 39 |
└── .phpcs.xml.dist # PHPCS configuration |
| 40 |
``` |
| 41 |
|
| 42 |
### Key Architecture |
| 43 |
|
| 44 |
- `edit_flow` class — Main plugin class, loads and manages modules |
| 45 |
- Each module in `modules/` is a self-contained feature with its own views, scripts, and styles |
| 46 |
- `common/` contains the base `EF_Module` class and shared utilities |
| 47 |
|
| 48 |
### Dependencies |
| 49 |
|
| 50 |
- **Dev**: `automattic/vipwpcs`, `yoast/wp-test-utils` |
| 51 |
- **JS**: Has `package.json` with build tooling and Playwright for E2E tests |
| 52 |
|
| 53 |
## Commands |
| 54 |
|
| 55 |
```bash |
| 56 |
composer cs # Check code standards (PHPCS) |
| 57 |
composer cs-fix # Auto-fix code standard violations |
| 58 |
composer lint # PHP syntax lint |
| 59 |
composer test:integration # Run integration tests (requires wp-env) |
| 60 |
composer test:integration-ms # Run multisite integration tests |
| 61 |
composer coverage # Run tests with HTML coverage report |
| 62 |
|
| 63 |
npm run test-e2e # Run Playwright E2E tests |
| 64 |
npm run build # Build JS/CSS assets |
| 65 |
``` |
| 66 |
|
| 67 |
**Note:** This plugin has integration tests and E2E tests, but no separate PHP unit test suite. |
| 68 |
|
| 69 |
## Conventions |
| 70 |
|
| 71 |
Follow the standards documented in `~/code/plugin-standards/` for full details. Key points: |
| 72 |
|
| 73 |
- **Commits**: Use the `/commit` skill. Favour explaining "why" over "what". |
| 74 |
- **PRs**: Use the `/pr` skill. Squash and merge by default. |
| 75 |
- **Branch naming**: `feature/description`, `fix/description` from `develop`. |
| 76 |
- **Testing**: Integration tests for PHP, Playwright E2E tests for UI interactions. New PHP tests should be integration tests. |
| 77 |
- **Code style**: WordPress coding standards via PHPCS. Tabs for indentation. |
| 78 |
- **i18n**: All user-facing strings must use the `edit-flow` text domain. |
| 79 |
|
| 80 |
## Architectural Decisions |
| 81 |
|
| 82 |
- **Modular architecture**: Each feature (calendar, custom statuses, notifications, etc.) is a self-contained module in `modules/`. This is the plugin's core architectural pattern. New features should be added as new modules, not by extending existing ones. |
| 83 |
- **Module base class**: All modules extend `EF_Module` from `common/`. This provides shared infrastructure (settings registration, module activation/deactivation). |
| 84 |
- **Two main files**: `edit_flow.php` (underscore) is the real main file. `edit-flow.php` (hyphen) is a redirect for backward compatibility. Do not remove the redirect file. |
| 85 |
- **WordPress.org hosted**: This plugin is publicly distributed on WordPress.org. Changes must maintain backward compatibility for all users, not just VIP customers. |
| 86 |
- **E2E testing with Playwright**: UI-heavy features (calendar, editorial comments) are tested with Playwright. Use E2E tests for complex UI interactions, integration tests for PHP logic. |
| 87 |
- **Global namespace (legacy)**: All classes are in the global namespace with the `EF_` prefix. This is legacy — do not introduce namespaced classes alongside global ones without a migration plan. |
| 88 |
|
| 89 |
## Common Pitfalls |
| 90 |
|
| 91 |
- Do not edit WordPress core files or bundled dependencies in `vendor/`. |
| 92 |
- Run `composer cs` before committing. CI will reject code standard violations. |
| 93 |
- Integration tests require `npx wp-env start` running first. |
| 94 |
- **The main file has an underscore** (`edit_flow.php`), not a hyphen. The hyphenated `edit-flow.php` is just a redirect. Do not add logic to the redirect file. |
| 95 |
- **Modules are self-contained**: Do not create cross-dependencies between modules. If module A needs data from module B, use WordPress hooks/filters as the interface. |
| 96 |
- **WordPress.org compatibility**: This plugin serves a broad user base. Do not add VIP-specific code without graceful fallbacks for non-VIP environments. |
| 97 |
- Custom post statuses interact with WordPress core's status system in complex ways. Test custom status changes with Gutenberg and the Classic Editor — they behave differently. |
| 98 |
- The editorial calendar uses JavaScript date handling. Be careful with timezone issues — WordPress stores dates in UTC but displays them in the site's configured timezone. |
| 99 |
- Do not add new modules without considering the settings UI, activation/deactivation flow, and module dependencies. |
| 100 |
- Asset builds (`npm run build`) must be run before committing changes to JS/CSS source files. Built assets in `build/` and `dist/` should be committed. |
| 101 |
|
