Developing

Developing ODD

Requirements

• Node.js 20+
• Python 3 with requirements-catalog.txt
• PHP 8.1+
• Composer dependencies for PHPCS/PHPUnit
• Docker, WP-CLI, and Playwright for the local WordPress browser test

First setup

npm ci
composer install
python3 -m pip install -r requirements-catalog.txt

ODD Notes workflow

Edit the TypeScript under _tools/catalog-sources/apps/odd-notes/src/, then run:

npm run build:notes
npm test

The generated bundle-src/assets/js/odd-notes.min.js is committed because catalog packaging consumes the finished app tree. CI and the pre-commit hook rebuild it and fail when it differs.

If app behavior or assets should reach existing installs, bump both:

• _tools/catalog-sources/apps/odd-notes/meta.json
• _tools/catalog-sources/apps/odd-notes/bundle-src/manifest.json

Catalog workflow

Build the production catalog only after the app source is ready:

python3 _tools/build-catalog.py
ODD_VALIDATE_REBUILD=1 odd/bin/validate-catalog
odd/bin/validate-blueprint
git diff --check

Generated production files live under site/catalog/v1/ and odd/data/fallback-registry.json.

For a non-live candidate:

npm run catalog:preview

Use the preview Playground launcher for preview-catalog QA.

PHP and package checks

composer phpcs
odd/bin/check-version
odd/bin/check-plugin-metadata
odd/bin/build-zip
odd/bin/check-zip-contents
odd/bin/check-licenses

Local PHPUnit requires the WordPress test bootstrap constants and database. If they are unavailable, report PHPUnit as skipped; do not describe PHPCS or browser tests as PHPUnit.

Real browser test

bash bin/e2e-local.sh all e2e/panel.spec.ts

The runner provisions a local WordPress/OpenStation instance, serves the freshly built catalog through a hermetic fixture, installs or replaces ODD Notes, runs Playwright, and cleans up the web-server process. Docker database volumes and cached WordPress files can be recreated independently; the runner checks both before reuse.

Useful locations

odd/includes/notes/                         Notes service and REST controller
odd/src/panel/                              Apps-only Shop UI
_tools/catalog-sources/apps/odd-notes/src/ ODD Notes source
tests/app-only/                             focused JS/PHP tests
e2e/panel.spec.ts                           WordPress browser smoke
bin/e2e-local.sh                            local provisioning runner

Playground lanes

• Current main: https://odd.regionallyfamous.com/go/dev/
• Preview catalog: https://odd.regionallyfamous.com/go/preview/
• Stable WordPress.org release: https://odd.regionallyfamous.com/go/

Playground caches aggressively. Use the launcher instead of constructing an unversioned blueprint URL; the dev launcher derives its cache key from the newest main commit.