Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (101 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 4.15 KB
Raw

Contributing to Spectre Base Theme

Spectre Base Theme is a WordPress theme foundation with a Vite build pipeline, a single theme JavaScript entry, and a single emitted theme CSS bundle.

Shared AI workflow

  • Repo-shared Copilot support files live in .github/copilot-instructions.md, .github/instructions/, .github/prompts/, and .github/agents/.
  • Use the Release Ready prompt for production-readiness and dependency-update audits.
  • Keep release handoff notes aligned with .codex/handoff-template.md.

Quick start

  1. Install dependencies:

    npm install

  2. Start development:

    npm run dev

  3. Build production assets:

    npm run build

  4. Validate the theme asset contract:

    npm run check:assets

  5. Validate PHP syntax:

    npm run lint:php

What lives where

  • src/js/main.ts is the single theme JavaScript entry.
  • src/styles/main.css is the theme stylesheet source imported by src/js/main.ts.
  • spectre-theme/ contains the WordPress theme PHP templates and metadata.
  • spectre-theme/dist/ contains compiled assets generated by Vite. Do not edit it by hand.

The deployable WordPress theme directory in this repository is spectre-theme/. The package and repository name remain spectre-base.

File safety

File / directory Status Note
src/js/main.ts Source of truth Edit freely
src/styles/main.css Source of truth Edit freely
spectre-theme/ (PHP, JSON) Source of truth Edit freely
spectre-theme/dist/ Generated Never edit directly — output of npm run build
spectre-theme/dist/.vite/manifest.json Generated Validated by npm run check:assets
vite.config.ts Source of truth Edit when changing build behavior
package.json Source of truth Version must stay in sync with style.css and readme.txt

Ownership boundaries

  • Keep PHP focused on WordPress structure, data access, and template flow.
  • Keep theme styling and client behavior in src/.
  • Consume @phcdevworks/spectre-tokens and @phcdevworks/spectre-ui; do not redefine token values or recreate the shared styling layer locally.
  • Do not add additional theme asset entrypoints unless the theme contract is intentionally changing.

Before opening a pull request

Run the full validation suite locally:

npm run check

If your change affects WordPress rendering, verify both:

  • Development mode loading from the Vite dev server
  • Production mode loading from spectre-theme/dist/.vite/manifest.json

Contract-Impacting Changes

Any change that touches a public theme surface requires explicit classification before review. Public surfaces include WordPress hooks and filters, template contracts, asset handles, theme metadata, deployable files in spectre-theme/, README usage, and generated asset output.

Step-by-step checklist:

  1. Identify the change classification: additive, semantic change, breaking, or N/A.

  2. Update source, docs, theme metadata, and CHANGELOG.md [Unreleased] together.

  3. Confirm no hardcoded visual values, local tokens, client-specific branding, or starter-theme boundary violations were introduced.

  4. Regenerate assets with npm run build if output changed.

  5. Run the full validation command:

    npm run check

  6. Stop for Bradley Potts approval before changing public hooks, filters, asset handles, theme version metadata, or any reusable theme contract in a breaking way.

Notes for contributors

  • Follow the existing file structure before creating new folders.
  • Prefer small template parts over large abstractions.
  • Update README or contributor docs when the developer workflow changes.
  • Move reusable visual patterns to @phcdevworks/spectre-ui rather than expanding the WordPress shell.

Questions

Open an issue or discussion in this repository if you need direction before making a larger change.

Code of Conduct

By participating in this project, you agree to follow the Code of Conduct.

License

By contributing, you agree that your contributions will be licensed under the MIT License.