76 lines
4.1 KiB
Markdown
76 lines
4.1 KiB
Markdown
|
# 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.
|
||
|
|
|