OTSSigns-Website/copilot-instructions.md

GitHub Copilot & Contributor Instructions

Purpose: guidance for using GitHub Copilot (and for humans) when working on this repo.

Repo overview

• theme/: WordPress theme source (PHP, theme assets, includes). Edit here for theme behavior, templates, and assets.
• pages/: PHP page templates used by WordPress (e.g., about.php, contact.php). These are page-level templates or example pages.
• theme/assets/: CSS/JS/SVG used by the theme. assets/css/main.css and assets/js/main.js are the main files.
• theme/inc/: PHP helpers and feature modules (enqueueing, AJAX handlers, setup, theme defaults, generator, settings).
• parts/: small HTML snippets (header/footer) included by templates.
• patterns/ and templates/: reusable patterns and template HTML files.

Goals when editing

• Keep changes small and focused per PR.
• Preserve WordPress conventions (use wp_enqueue_script/wp_enqueue_style, action/filter hooks, and template hierarchy).
• Avoid breaking backward compatibility for theme consumers unless explicitly required.

Local development (recommended quick steps)

• Testing is handled by the repository owner; do not run WordPress locally unless explicitly requested.

Manual checks you can run locally before submitting changes:

• PHP syntax: php -l path/to/file.php
• Theme header: ensure style.css at theme/style.css contains valid theme metadata.

Editing the theme

• Primary entry points: theme/functions.php, theme/index.php, theme/assets/, and theme/inc/*.
• Add / modify reusable sections in parts/header.html and parts/footer.html.
• For new templates: follow WP template naming (e.g., page-{$slug}.php) or create a template with a /* Template Name: ... */ comment.
• Use theme/inc/enqueue.php (or existing helpers) to add scripts/styles — keep asset handles unique and versioned.

Pages folder usage

• pages/*.php contains standalone page templates or examples. When adding a new page template, document how it should be attached in WP admin (page template comment or theme settings).

Testing & validation

• Run php -l on changed PHP files before committing.
• For CSS/HTML, use browser devtools and the W3C validator for critical pages.
• If adding JS, test in Safari and Chrome on macOS (this repo is tested on macOS by default).

Code style & safety

• Follow existing code patterns in theme/.
• Escape outputs (use esc_html(), esc_attr(), wp_kses_post() where appropriate) for user-facing output.
• Nonces: use wp_nonce_field()/check_admin_referer() for forms/AJAX in theme/inc/ajax.php.

Commit and PR guidance

• Keep commits focused: one feature/bugfix per PR.
• Provide a clear PR description: what changed, why, and how to test locally.
• Run php -l and a quick manual smoke-test before opening PR.

Using GitHub Copilot effectively for this repo

• Provide context in prompts: mention exact file path(s) and constraints (WordPress version targets, PHP version, browser compatibility).
• Good prompt pattern:
  • Short summary of intent.
  • Files or functions to change (provide paths).
  • Constraints (e.g., "must use wp_enqueue_script", "no breaking changes to header markup").
  • How to test the change.

Example Good Prompt: "Refactor theme/inc/enqueue.php to register and enqueue a new frontend script theme-main from theme/assets/js/main.js. Use wp_enqueue_script with dependency jquery and version based on file filemtime. Make sure it loads in the footer. Show the exact code to add and where."

Example Bad Prompt: "Make the theme faster." (too vague — include file, objective, and measurable change)

When to ask for human review

• Changes to security-sensitive code (nonce handling, AJAX endpoints).
• Template structure changes that may break theme consumers.
• Large refactors that affect multiple parts of the theme.

Owner / Maintainers

• If unsure, open a draft PR and assign it to the repository owner for review.

---

If you want, I can also:

• Add a quick Makefile or NPM scripts for common checks (PHP lint, CSS/JS lint).
• Add a sample wp-env configuration for one-command local setup.