Developing

Developing

Prerequisites

• WordPress 6.0+ with WP Desktop Mode v0.5.0+ active.
• PHP 7.4+.
• Python 3 on PATH (used only by the validators and by _tools/ content scripts).
• git with hooks enabled — run git config core.hooksPath .githooks once after cloning.

No Node or npm step. All JavaScript in the plugin is plain ES5-compatible and loaded via wp_enqueue_script.

Local iteration

1. Clone this repo into wp-content/plugins/odd/ (or symlink it).

2. Activate ODD alongside WP Desktop Mode.

3. Edit files and refresh — there is no build step.

4. For a full validation pass before pushing:

   odd/bin/check-version \
     && odd/bin/validate-scenes \
     && odd/bin/validate-icon-sets \
     && odd/bin/build-zip

Validators

• odd/bin/validate-scenes — every scene in src/wallpaper/scenes.json has a JS module, a preview WebP, and a wallpaper WebP on disk. Fails CI on drift.
• odd/bin/validate-icon-sets — every assets/icons/<slug>/manifest.json parses, declares slug / label / franchise / accent / icons, and every icon referenced on disk parses as well-formed XML with a viewBox (or width+height). Explicitly scans for control bytes < 0x20 outside \t\n\r in SVG bodies — see Gotchas.
• odd/bin/check-version — the Version: header in odd/odd.php matches the ODD_VERSION constant. Also mirrored by the pre-commit hook.

CI

.github/workflows/ci.yml runs on every PR and push to main:

• validate-scenes — manifest + assets for every scene.
• validate-icon-sets — manifest + SVGs for every set.
• check-version — header + constant in odd.php agree.
• json-valid — blueprint.json, scenes.json, drifters.json, every icon manifest parses.
• zip-budget — odd/bin/build-zip with a 35 MB cap; uploads odd.zip as a workflow artifact.

Pre-commit hook

.githooks/pre-commit runs odd/bin/check-version only when odd/odd.php is in the commit — catches the "bumped Version: header but forgot ODD_VERSION" class of mistake locally instead of burning a tag cycle.

Install once after cloning:

git config core.hooksPath .githooks

Skip in an emergency with git commit --no-verify.

Testing in Playground

The blueprint at blueprint.json installs ODD's latest release ZIP + WP Desktop Mode into a fresh WordPress, logs you in, and pre-selects the ODD wallpaper.

To test an unreleased branch:

1. Push the branch.
2. Temporarily edit blueprint.json locally to point url at https://raw.githubusercontent.com/RegionallyFamous/odd/<branch>/odd/odd.php style — or serve a ZIP via odd/bin/build-zip and upload it somewhere CORS-friendly.
3. Open https://playground.wordpress.net/?blueprint-url=<your-blueprint-url>.

raw.githubusercontent.com and github.com/*/releases/download/... both serve with access-control-allow-origin: *. Other hosts usually don't — verify with curl -H "Origin: https://playground.wordpress.net" -I <url> before pointing a blueprint at a new URL.