Skip to content

[Docs] Document the daily local-development workflow #772

Description

@divyarajmasani

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

  1. Start and stop the site: verified wp-env commands, development/test URLs and ports, and a short note for an existing local WordPress installation.
  2. 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.
  3. Edit and see changes: watch command, frontend reload, editor refresh, and a simple success check.
  4. Configure your environment: minimum .env.local and WordPress settings; link to advanced HMR, HTTPS, and custom-port instructions.
  5. Check a change: focused tests and lint commands; distinguish host and container execution.
  6. Build for delivery: production command, expected artifacts, and the repository's verified build-output policy.
  7. 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

  • A developer can start the site, edit source, see the result, run checks, and create a production build.
  • Source files and generated output are clearly distinguished.
  • Commands and port defaults match the supported revision.
  • Test commands terminate when intended; watch commands are identified.
  • Common failures have concrete next actions.
  • Advanced configuration and tool internals do not obscure the daily workflow.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions