[Docs] Add comprehensive coding standards and linting improvements #3
Conversation
- Introduced JSON schema for wp-env configuration files. - Established accessibility guidelines based on WCAG 2.2 AA. - Documented alignment decisions and matrix for coding practices. - Outlined standards for block development and inline documentation. - Created checklists for accessibility, performance, PRs, releases, and security. - Compiled common standards for PHP, JS, CSS, HTML, and documentation. - Defined CSS standards including BEM naming and fluid typography. - Added examples for blocks, CSS, HTML, JS, and PHP. - Specified theme.json guidelines for token definitions and formatting. - Implemented tooling documentation for CI, EditorConfig, ESLint, PHPCS, Stylelint, and WooCommerce guidelines.
- Implemented `lint-agents.js` to validate AGENTS.md and AGENT.md files structure. - Created `migrate-copilot-extensions.js` to rename legacy asset extensions to new plural forms, with deprecation stubs for legacy files. - Added a backup for the YAML parser in `yaml-parser-backup.js`. - Updated `.prettierignore` to exclude additional files and directories from formatting. - Introduced a new Stylelint configuration in `.stylelintrc copy.json` and linked it in `stylelint.config.js`. - Configured Webpack with multiple entry points for CSS and JS files, utilizing `RemoveEmptyScriptsPlugin` to clean up empty scripts.
… focus and improve maintainability
…unctionalities, including accessibility review, lint fixing, block generation, and BEM refactoring. Update workspace settings for improved development experience.
- Removed stylelint configuration and related linting scripts from package.json. - Deleted webpack.config.js as it is no longer needed. - Added a new WordPress documentation specialist agent for inline documentation. - Introduced an interactive chat mode for generating and reviewing WordPress documentation. - Created comprehensive instructions for WordPress inline documentation standards. - Added a prompt for generating WordPress-compliant inline documentation for PHP and JavaScript. - Updated package.json to remove stylelint dependencies and adjust linting scripts accordingly.
ashleyshaw
requested review from
Justinabes007,
ZaredRogers,
brandonmarshal,
josearmandoabreu,
krugazul,
serenvdmerwe and
tibiii
|
Important Review skippedMore than 25% of the files skipped due to max files limit. The review is being skipped to prevent a low-quality review. 101 files out of 300 files are above the max files limit of 100. Please upgrade to Pro plan to get higher limits. You can disable this status message by setting the Warning
|
There was a problem hiding this comment.
Hi Lightspeed team,
Please review the newly added documentation and Copilot instruction files in this branch. These updates include agent guides, markdown standards, and best practices for accessibility, performance, and security.
Kindly check each file for accuracy, clarity, and compliance with our coding standards. Pay special attention to accessibility, security, and WordPress-specific guidance. Feedback and suggestions for improvement are welcome.
Thank you!
Ash
There was a problem hiding this comment.
Pull Request Overview
This pull request adds comprehensive coding standards and linting improvements for WordPress development, introducing new Copilot documentation assets and instruction files to improve onboarding, code quality, and contributor guidance. The changes focus on establishing consistent documentation standards, AI-assisted development workflows, and quality gates for WordPress block themes and plugins.
Key changes include:
- Addition of WordPress inline documentation Copilot assets following official coding standards
- Enhanced VS Code configuration with proper file associations for plural extensions
- Repository cleanup removing unnecessary build tool configurations
Reviewed Changes
Copilot reviewed 206 out of 741 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
docs-unified/ai-copilot/prompts/*.md |
New WordPress-specific prompts for block patterns, Gutenberg blocks, theme.json configuration, and accessibility auditing |
.github/prompts/*.prompts.md |
WordPress inline documentation generator and various development prompts |
.vscode/settings.json |
Enhanced file associations for plural extensions and improved MCP server configuration |
.github/scripts/*.js |
Updated build scripts with support for new file extensions and improved collection validation |
| Configuration files | Cleanup of unnecessary build tools and enhanced linting configurations |
Comments suppressed due to low confidence (1)
docs-unified/ai-copilot/prompts/accessibility-expert.chatmode.md:1
- This concluding statement excellently demonstrates the people-first language and inclusive design principles outlined in the accessibility coding guidelines. This is a good example of how to frame accessibility work positively and comprehensively.
---
| # Prompt — PR Description | ||
|
|
||
| Template for strong PRs. |
There was a problem hiding this comment.
This file lacks frontmatter metadata required by the coding guidelines. According to CodingGuidelineID 1000000, prompt files should include markdown front matter with fields like mode, description, model, and tools. Add proper YAML frontmatter to make this file compliant with the established standards.
| # Prompt: Playwright e2e scenarios | ||
|
|
||
| Happy path + edge case; stable selectors; deterministic. |
There was a problem hiding this comment.
Missing required frontmatter metadata. According to the coding guidelines, prompt files should include YAML frontmatter with at least a description field and mode field specified as either 'agent' or 'ask'. Add proper frontmatter to comply with the prompt file guide standards.
| # Agent — Performance Coach | ||
|
|
||
| Checklist for Core Web Vitals. |
There was a problem hiding this comment.
This agent file lacks the required frontmatter structure. Per CodingGuidelineID 1000000, agent files should include markdown front matter with a description field that is not empty and wrapped in single quotes. The current content is too minimal for an agent specification.
| @@ -0,0 +1,20 @@ | |||
| --- | |||
| mode: 'agent' | |||
| name: 'Scrumban Project Planner' | |||
There was a problem hiding this comment.
The name field in the frontmatter is not part of the standard schema according to the coding guidelines. Chat mode files should focus on description, mode, model, and tools fields. Consider removing the name field or clarifying its purpose if it's intentionally extended beyond the standard.
| name: 'Scrumban Project Planner' |
| --- | ||
| applyTo: "**/*.{js,jsx,ts,tsx}" | ||
| description: "JavaScript and React development standards for WordPress Gutenberg blocks and modern WordPress development" | ||
| license: "GPL-3.0-or-later" |
There was a problem hiding this comment.
The instruction file includes a license field in the frontmatter, but according to CodingGuidelineID 1000000, instruction files should focus on applyTo and description fields. While the license information is valuable, consider whether it belongs in the coding guidelines or should be documented separately to maintain frontmatter consistency.
| license: "GPL-3.0-or-later" |
| if(!item.path||typeof item.path!=="string") return `Item ${i+1} must have a path string`; | ||
| if(!item.kind||typeof item.kind!=="string") return `Item ${i+1} must have a kind string`; | ||
| if(!['prompt','instruction','chat-mode'].includes(item.kind)) return `Item ${i+1} kind must be one of: prompt, instruction, chat-mode`; | ||
| if(!['prompt','instruction','chat-mode','agent'].includes(item.kind)) return `Item ${i+1} kind must be one of: prompt, instruction, chat-mode, agent`; |
There was a problem hiding this comment.
The validation logic for file extensions is duplicated and complex. Consider extracting the extension validation logic into a separate function to improve maintainability and reduce code duplication across lines 50-53.
| } | ||
| inFM = false; fmDone = false; | ||
| if (/(\.prompt|\.chatmode|\.instructions)\.md$/.test(filePath)) { | ||
| if (CURRENT_EXT_PATTERN.test(filePath) || LEGACY_EXT_PATTERN.test(filePath) || AGENT_EXT_PATTERN.test(filePath)) { |
There was a problem hiding this comment.
The file extension pattern matching is becoming complex with multiple patterns. Consider consolidating these patterns into a single comprehensive regex or creating a helper function to determine if a file matches any of the supported extensions.
| @@ -0,0 +1,3 @@ | |||
| # Prompt — PR Description | |||
|
|
|||
| Template for strong PRs. | |||
There was a problem hiding this comment.
This file lacks substantive content. It should either include the actual PR description template content or reference where the template can be found. Consider adding the template structure or linking to the actual template file.
| Template for strong PRs. | |
| ## PR Description Template | |
| **Summary** | |
| <!-- Briefly describe the purpose of this PR and what it does. --> | |
| **Changes** | |
| <!-- List the main changes made in this PR. --> | |
| **Testing** | |
| <!-- Describe how you tested your changes and any relevant test results. --> | |
| **Related Issues** | |
| <!-- Link to any related issues or pull requests. --> | |
| **Checklist** | |
| - [ ] I have reviewed the code and tested it locally | |
| - [ ] Documentation has been updated as needed | |
| - [ ] Related issues have been linked | |
| - [ ] All tests pass |
| @@ -0,0 +1,3 @@ | |||
| # Prompt: Playwright e2e scenarios | |||
|
|
|||
| Happy path + edge case; stable selectors; deterministic. | |||
There was a problem hiding this comment.
This file provides only a one-line description. For a prompt file, it should include more detailed guidance on writing Playwright tests, such as selector best practices, test structure, and common patterns. The content is too minimal to be useful as a prompt.
| Happy path + edge case; stable selectors; deterministic. | |
| Write Playwright end-to-end (e2e) tests for the described scenario. Follow these best practices: | |
| ## Test Structure | |
| - Use `describe` blocks to group related tests. | |
| - Use clear, descriptive test names. | |
| - Structure tests with setup and teardown logic as needed (e.g., `beforeEach`, `afterEach`). | |
| ## Selector Best Practices | |
| - Prefer stable selectors such as `data-testid` or `aria-label` attributes. | |
| - Avoid brittle selectors like those based on CSS classes or element order. | |
| - Use Playwright's built-in selector engines for reliability. | |
| ## Coverage | |
| - Write tests for both the happy path (expected user flow) and edge cases (unexpected or error conditions). | |
| - Ensure tests cover important user interactions and error handling. | |
| ## Determinism & Stability | |
| - Avoid relying on timing (e.g., `waitForTimeout`) unless necessary. | |
| - Use assertions that wait for expected conditions (e.g., `await expect(...)`). | |
| - Clean up state between tests to prevent cross-test interference. | |
| ## Common Patterns | |
| - Use fixtures for reusable setup. | |
| - Assert on both UI changes and underlying data/state when possible. | |
| - Mock network requests if needed for determinism. | |
| ## Example | |
| ```typescript | |
| import { test, expect } from '@playwright/test'; | |
| test.describe('Login flow', () => { | |
| test('should log in successfully with valid credentials', async ({ page }) => { | |
| await page.goto('https://example.com/login'); | |
| await page.fill('[data-testid="username-input"]', 'user1'); | |
| await page.fill('[data-testid="password-input"]', 'password123'); | |
| await page.click('[data-testid="login-button"]'); | |
| await expect(page).toHaveURL('https://example.com/dashboard'); | |
| await expect(page.locator('[data-testid="welcome-message"]')).toBeVisible(); | |
| }); | |
| test('should show error with invalid credentials', async ({ page }) => { | |
| await page.goto('https://example.com/login'); | |
| await page.fill('[data-testid="username-input"]', 'user1'); | |
| await page.fill('[data-testid="password-input"]', 'wrongpassword'); | |
| await page.click('[data-testid="login-button"]'); | |
| await expect(page.locator('[data-testid="error-message"]')).toBeVisible(); | |
| }); | |
| }); |
Follow these guidelines to write robust, maintainable Playwright tests.
| # PHP Guidelines | ||
|
|
||
| - Use actions/filters judiciously. Keep theme logic thin; prefer companion plugin for business logic. | ||
| - Escape early (`esc_html`, `esc_attr`, `wp_kses_post`); internationalise (`__`, `_x`, `_n`). | ||
| - Provide PHPUnit tests for helpers/filters. |
There was a problem hiding this comment.
This instructions file is missing the required frontmatter with applyTo field that specifies which files these instructions apply to. According to the instruction file guide in the custom guidelines, instructions files must have an applyTo field with glob patterns.
| # Instruction — Performance | ||
|
|
||
| **Goals:** Keep patterns light and fast. | ||
| **Rules** | ||
| - Shallow nesting: avoid redundant Groups. | ||
| - Use optimised placeholders images (reasonable intrinsic size). | ||
| - Avoid heavy dynamic queries in previews; limit counts. | ||
| - Zero inline CSS; rely on theme tokens. |
There was a problem hiding this comment.
This instructions file is missing the required frontmatter with applyTo field that specifies which files these instructions apply to. All instruction files should include frontmatter with at least the applyTo field.
| --- | ||
| mode: 'agent' | ||
| name: 'Scrumban Project Planner' | ||
| description: 'Plan milestones, epics (parent issues), and stories (child issues) for GitHub Projects.' | ||
| --- |
There was a problem hiding this comment.
[nitpick] Chat mode files should follow the naming convention where the name field is derived from the filename. The file is named plan.chatmode.md but the name field is 'Scrumban Project Planner'. Consider renaming the file to scrumban-project-planner.chatmode.md for consistency.
| # Coding Standards | ||
|
|
||
| - **PHP**: WordPress coding standards; PHPCS (WordPress‑Extra) clean; PHPStan level per repo. | ||
| - **JS/TS**: ESLint + Prettier; modern JS; avoid jQuery unless required. | ||
| - **CSS**: Use tokens from `theme.json`; avoid hardcoded colours; respect `prefers-reduced-motion`. | ||
| - **Security**: Escape output, sanitise input, nonces/capabilities in admin. | ||
| - **Performance**: Avoid N+1 queries; lazy‑load media; keep bundles small. |
There was a problem hiding this comment.
This instructions file is missing the required frontmatter with applyTo field. According to the custom guidelines, instruction files must specify which files they apply to using glob patterns in the applyTo field.
Pull Request: Add Copilot Docs and Instruction Files
Description
This pull request introduces new documentation and Copilot instruction files to the repository. It includes agent guides, markdown standards, accessibility, performance, and security best practices, aiming to improve onboarding, code quality, and contributor guidance.
Related Issue: Fixes #[issue-number] (replace with actual issue number)
Type of Change
Quality Gate Checklist
npm run lang:en-gbapplied if broad changes)npm run build) if catalogue changes madecoding-standards/Testing Instructions
npm run buildand verify no unexpected diffs.Screenshots (if applicable)
N/A
Changelog Entry
Category: Added
Entry: Added Copilot agent documentation, markdown standards, and best practice instruction files for accessibility, performance, and security.
Additional Context
This update is part of ongoing efforts to improve contributor experience and code quality. No breaking changes are introduced.
By submitting this pull request, I confirm that my contribution abides by the repository governance and will be licensed under the GPL-3.0-only licence.