Parent epic: #768 — Documentation epic
Base branch: theme-elementary-v2. Cover its functionality and subsequent changes based on it. Verify against the latest relevant v2 implementation and record the tested commit in the documentation PR.
Problem and scope
Local environment, asset, and verification instructions are scattered. Create docs/local-development.md around the tasks developers repeat after setup.
Proposed structure
- Start and stop the site: verified wp-env commands, development/test URLs and ports, and a short note for an existing local WordPress installation.
- Know what to edit: a small source → generated output map for assets and blocks; identify files developers should edit and generated files they should not.
- Edit and see changes: watch command, frontend reload, editor refresh, and a simple success check.
- Configure your environment: minimum .env.local and WordPress settings; link to advanced HMR, HTTPS, and custom-port instructions.
- Check a change: focused tests and lint commands; distinguish host and container execution.
- Build for delivery: production command, expected artifacts, and the repository's verified build-output policy.
- When it fails: symptom → check → next action entries for ports, Docker, assets, certificates, and test startup.
Consolidation and boundaries
- Keep
docs/asset-building-process.md as the deeper asset reference and docs/hmr.md as advanced configuration; update links and remove contradictory guidance.
- CONTRIBUTING should link here for commands and retain only contribution-specific expectations.
- End feature work with a behavior/checks review and an optional separate feature commit.
- Link separate implementation issues for broken aggregate test commands or other tooling defects.
Acceptance criteria
Parent epic: #768 — Documentation epic
Base branch:
theme-elementary-v2. Cover its functionality and subsequent changes based on it. Verify against the latest relevant v2 implementation and record the tested commit in the documentation PR.Problem and scope
Local environment, asset, and verification instructions are scattered. Create
docs/local-development.mdaround the tasks developers repeat after setup.Proposed structure
Consolidation and boundaries
docs/asset-building-process.mdas the deeper asset reference anddocs/hmr.mdas advanced configuration; update links and remove contradictory guidance.Acceptance criteria