Automattic/wordpress-activitypub / .agents/skills/dev
dev
VerifiedDevelopment workflows for WordPress ActivityPub plugin including wp-env setup, testing commands, linting, and build processes. Use when setting up development environment, running tests, checking code quality, building assets, or working with wp-env.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.6 KB |
SKILL.md
View on GitHub---
name: dev
description: Development workflows for WordPress ActivityPub plugin including wp-env setup, testing commands, linting, and build processes. Use when setting up development environment, running tests, checking code quality, building assets, or working with wp-env.
---
# ActivityPub Development Cycle
Quick reference for common development workflows in the WordPress ActivityPub plugin.
## Quick Reference
### Environment Management
```bash
npm run env-start # Start WordPress at http://localhost:8888.
npm run env-stop # Stop WordPress environment.
npm run env-destroy # Delete the environment: containers, database, uploads.
npm run env -- status # Show the URLs and ports of the environment.
```
### In a Worktree
Every directory gets its own wp-env environment, so a worktree runs its tests in its own containers and database, without touching the main checkout or other worktrees. Never run a worktree's tests in another directory's environment: they share its test database.
```bash
ln -s /path/to/main/checkout/node_modules node_modules # Reuse the Node packages.
composer install # vendor/ must be real, the container mounts the worktree.
echo '{ "port": 8890, "testsPort": 8891 }' > .wp-env.override.json # Own ports, ignored by git.
npm run env-start
npm run env-test -- --filter=Test_Name
npm run env-destroy # Before removing the worktree.
```
Never change the ports in `.wp-env.json`: the main checkout keeps 8888 and 8889. Pick a pair that no other environment uses, running or not: `lsof -nP -iTCP:<port> -sTCP:LISTEN` prints nothing for a free port, and the `.wp-env.override.json` files of the other worktrees list the ports they have taken.
### Testing Commands
```bash
npm run env-test # Run all PHP tests.
npm run env-test -- --filter=pattern # Run tests matching pattern.
npm run env-test -- path/to/test.php # Run specific test file.
npm run env-test -- --group=name # Run tests with @group annotation.
npm run test:e2e # Run Playwright E2E tests.
npm run test:e2e:debug # Debug E2E tests.
```
### Code Quality
```bash
composer lint # Check PHP coding standards.
composer lint:fix # Auto-fix PHP issues.
npm run lint:js # Check JavaScript.
npm run lint:css # Check CSS styles.
npm run format # Format all code (wp-scripts).
```
### Building Assets
```bash
npm run build # Build for production (formatted and minified).
npm run dev # Start development watch mode.
```
### Code Coverage
```bash
npm run env-start -- --xdebug=coverage # Start with coverage support.
npm run env-test -- --coverage-text # Generate text coverage report.
npm run env-test -- --coverage-html ./coverage # Generate HTML report.
```
## Comprehensive Documentation
See `docs/development-environment.md` for detailed setup instructions.
See `tests/README.md` for comprehensive testing guidance.
See `docs/code-linting.md` for linting configuration and standards.
## Pre-commit Hooks
The repository uses automated pre-commit hooks (`.githooks/pre-commit`) that run automatically on `git commit`:
1. **Sort PHP imports** - Automatically organizes use statements.
2. **Check unused imports** - Prevents unused use statements.
3. **Validate test patterns** - Blocks `remove_all_filters('pre_http_request')`.
4. **Run PHPCS auto-fix** - Applies coding standards automatically.
5. **Format JavaScript** - Runs wp-scripts formatter.
**IMPORTANT:** Hooks modify staged files automatically. Always review changes before committing. If hooks make changes, you'll need to stage them and commit again.
**Setup:** Hooks are installed by `npm run prepare` (runs automatically after `npm install`).
## Common Development Workflows
### Initial Setup
```bash
git clone git@github.com:Automattic/wordpress-activitypub.git
cd wordpress-activitypub
npm install # Also runs 'npm run prepare' to install hooks.
composer install
npm run env-start # WordPress at http://localhost:8888.
```
### Making Changes Workflow
```bash
# 1. Make code changes.
# 2. Run relevant tests.
npm run env-test -- --filter=FeatureName
# 3. Check code quality (optional - pre-commit hook does this).
composer lint
npm run lint:js
# 4. Commit (pre-commit hook runs automatically).
git add .
git commit -m "Description"
# Hook may modify files - review and stage again if needed.
```
When the admin app imports from a `@wordpress/*` package that the build externalizes to a `wp.*` global, check the export against what the plugin's minimum WordPress version ships (`wp-includes/js/dist/<package>.js`, or `typeof wp.<package>.<name>` in the browser), not against `node_modules`. Newer npm versions export names the shipped global does not have.
### Before Creating PR
```bash
# Run full test suite.
npm run env-test
# Build assets.
npm run build
# Final lint check.
composer lint
npm run lint:js
```
### Debugging Failing Tests
```bash
# Run with verbose output.
npm run env-test -- --verbose --filter=test_name
# Run single test file to isolate issue.
npm run env-test -- tests/phpunit/tests/path/to/test.php
# Check test groups.
npm run env-test -- --list-groups
npm run env-test -- --group=specific_group
```
### Fresh Environment
```bash
npm run env-stop
npm run env-start
# wp-env automatically sets up WordPress with debug mode and test users.
```
## Key Files
- `package.json` - npm scripts and dependencies.
- `composer.json` - PHP dependencies and lint scripts.
- `.wp-env.json` - wp-env configuration.
- `phpcs.xml` - PHP coding standards (custom WordPress rules).
- `.githooks/pre-commit` - Pre-commit automation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |