From 9d36b47f9fad830572f2eefe014f716032f7b53a Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Mon, 21 Apr 2025 04:12:51 +0100 Subject: [PATCH] Standardize Markdown bullet points to use asterisks instead of hyphens --- .ai-assistant.md | 116 +++++++++++++------------ .ai-workflows/code-review.md | 160 +++++++++++++++++++---------------- .wiki/Coding-Standards.md | 125 +++++++++++++-------------- wiki/Coding-Standards.md | 125 +++++++++++++-------------- 4 files changed, 271 insertions(+), 255 deletions(-) diff --git a/.ai-assistant.md b/.ai-assistant.md index 60838a8..4121396 100644 --- a/.ai-assistant.md +++ b/.ai-assistant.md @@ -6,50 +6,51 @@ This guide helps AI assistants understand the project structure, workflows, and This workspace may contain multiple repository folders. Always focus ONLY on the current repository you're working in and avoid hallucinating functionality from other repositories in the workspace. -- **Current Repository**: wp-plugin-starter-template-for-ai-coding -- **Repository Purpose**: A comprehensive starter template for WordPress plugins with best practices for AI-assisted development -- **Repository Scope**: All code changes, documentation, and functionality discussions should be limited to THIS repository only +* **Current Repository**: wp-plugin-starter-template-for-ai-coding +* **Repository Purpose**: A comprehensive starter template for WordPress plugins with best practices for AI-assisted development +* **Repository Scope**: All code changes, documentation, and functionality discussions should be limited to THIS repository only ## Project Overview -- **Plugin Name**: WordPress Plugin Starter Template -- **Plugin Slug**: wp-plugin-starter-template -- **Text Domain**: wp-plugin-starter-template -- **Namespace**: WPALLSTARS\PluginStarterTemplate -- **Version**: 0.1.1 -- **Requires WordPress**: 5.0+ -- **Requires PHP**: 7.0+ -- **License**: GPL-2.0+ +* **Plugin Name**: WordPress Plugin Starter Template +* **Plugin Slug**: wp-plugin-starter-template +* **Text Domain**: wp-plugin-starter-template +* **Namespace**: WPALLSTARS\PluginStarterTemplate +* **Version**: 0.1.10 +* **Requires WordPress**: 5.0+ +* **Requires PHP**: 7.0+ +* **License**: GPL-2.0+ ## Repository Structure -- **wp-plugin-starter-template.php**: Main plugin file with plugin headers -- **includes/**: Core plugin functionality - - **plugin.php**: Main plugin class that initializes everything - - **core.php**: Core functionality class - - **updater.php**: Update mechanism for multiple sources -- **admin/**: Admin-specific functionality - - **lib/**: Admin classes - - **css/**: Admin stylesheets - - **js/**: Admin JavaScript files -- **languages/**: Translation files -- **.github/workflows/**: GitHub Actions workflows -- **.ai-workflows/**: Documentation for AI assistants -- **.wiki/**: Wiki documentation templates +* **wp-plugin-starter-template.php**: Main plugin file with plugin headers +* **includes/**: Core plugin functionality + * **plugin.php**: Main plugin class that initializes everything + * **core.php**: Core functionality class + * **updater.php**: Update mechanism for multiple sources +* **admin/**: Admin-specific functionality + * **lib/**: Admin classes + * **css/**: Admin stylesheets + * **js/**: Admin JavaScript files +* **languages/**: Translation files +* **.github/workflows/**: GitHub Actions workflows +* **.ai-workflows/**: Documentation for AI assistants +* **.wiki/**: Wiki documentation templates ## Coding Standards This project follows the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/): -- Use 4 spaces for indentation, not tabs (this is a project-specific override of WordPress standards) -- Follow WordPress naming conventions: - - Class names: `Class_Name` - - Function names: `function_name` - - Variable names: `$variable_name` -- Use proper DocBlocks for all classes, methods, and functions -- Ensure all user-facing strings are translatable -- Validate and sanitize all inputs -- Escape all outputs +* Use 4 spaces for indentation, not tabs (this is a project-specific override of WordPress standards) +* Follow WordPress naming conventions: + * Class names: `Class_Name` + * Function names: `function_name` + * Variable names: `$variable_name` +* Use proper DocBlocks for all classes, methods, and functions +* Ensure all user-facing strings are translatable +* Validate and sanitize all inputs +* Escape all outputs +* Use asterisks (*) for bullet points in all Markdown files, not hyphens (-) ### Code Quality Tools @@ -76,10 +77,10 @@ This project uses several automated code quality tools to ensure high standards: ``` 5. **Continuous Integration Tools**: The project integrates with several code quality tools: - - **CodeRabbit**: AI-powered code review tool - - **CodeFactor**: Continuous code quality monitoring - - **Codacy**: Code quality and static analysis - - **SonarCloud**: Code quality and security analysis + * **CodeRabbit**: AI-powered code review tool + * **CodeFactor**: Continuous code quality monitoring + * **Codacy**: Code quality and static analysis + * **SonarCloud**: Code quality and security analysis Always run PHPCS and PHPCBF locally before committing code to ensure it meets the project's coding standards. @@ -103,15 +104,17 @@ When working in a multi-repository workspace, follow these guidelines to avoid c 6. **Verify Before Implementation**: Before implementing or documenting a feature, verify that it actually exists in the current repository by checking the codebase. +7. **Consistent Markdown Formatting**: Always use asterisks (*) for bullet points in Markdown files, not hyphens (-). + ## Internationalization (i18n) All user-facing strings should be translatable: -- Use `__()` for simple strings -- Use `_e()` for echoed strings -- Use `esc_html__()` for escaped strings -- Use `esc_html_e()` for escaped and echoed strings -- Always use the plugin's text domain: `wp-plugin-starter-template` +* Use `__()` for simple strings +* Use `_e()` for echoed strings +* Use `esc_html__()` for escaped strings +* Use `esc_html_e()` for escaped and echoed strings +* Always use the plugin's text domain: `wp-plugin-starter-template` Example: ```php @@ -120,26 +123,27 @@ echo esc_html__('This is a translatable string', 'wp-plugin-starter-template'); ## Security Best Practices -- Validate and sanitize all inputs -- Escape all outputs -- Use nonces for form submissions -- Use capability checks for user actions -- Follow the principle of least privilege +* Validate and sanitize all inputs +* Escape all outputs +* Use nonces for form submissions +* Use capability checks for user actions +* Follow the principle of least privilege ## Documentation -- Keep code comments up-to-date -- Update README.md and readme.txt when adding new features -- Update wiki documentation in the `.wiki/` directory -- Update changelog in both CHANGELOG.md and readme.txt +* Keep code comments up-to-date +* Update README.md and readme.txt when adding new features +* Update wiki documentation in the `.wiki/` directory +* Update changelog in both CHANGELOG.md and readme.txt +* Use asterisks (*) for bullet points in all Markdown files ## Git Workflow -- Create feature branches from `main` -- Use descriptive branch names (e.g., `feature/add-settings-page`) -- Make atomic commits with clear messages -- Create pull requests for review -- Tag releases with version numbers (e.g., `v1.0.0`) +* Create feature branches from `main` +* Use descriptive branch names (e.g., `feature/add-settings-page`) +* Make atomic commits with clear messages +* Create pull requests for review +* Tag releases with version numbers (e.g., `v1.0.0`) ## Developer Preferences diff --git a/.ai-workflows/code-review.md b/.ai-workflows/code-review.md index 0b427ff..0194156 100644 --- a/.ai-workflows/code-review.md +++ b/.ai-workflows/code-review.md @@ -1,6 +1,6 @@ # Code Review Guide for AI Assistants -This document provides guidance for AI assistants to help with code review for th plugin. +This document provides guidance for AI assistants to help with code review for this project. ## Code Review Checklist @@ -8,54 +8,54 @@ When reviewing code, check for the following: ### Functionality -- [ ] Does the code work as expected? -- [ ] Does it handle edge cases appropriately? -- [ ] Are there any logical errors? -- [ ] Is error handling implemented properly? +* [ ] Does the code work as expected? +* [ ] Does it handle edge cases appropriately? +* [ ] Are there any logical errors? +* [ ] Is error handling implemented properly? ### Code Quality -- [ ] Does the code follow WordPress coding standards? -- [ ] Is the code well-organized and easy to understand? -- [ ] Are there any code smells (duplicate code, overly complex functions, etc.)? -- [ ] Are functions and variables named appropriately? -- [ ] Are there appropriate comments and documentation? +* [ ] Does the code follow WordPress coding standards? +* [ ] Is the code well-organized and easy to understand? +* [ ] Are there any code smells (duplicate code, overly complex functions, etc.)? +* [ ] Are functions and variables named appropriately? +* [ ] Are there appropriate comments and documentation? ### Security -- [ ] Is user input properly validated and sanitized? -- [ ] Is output properly escaped? -- [ ] Are capability checks used for user actions? -- [ ] Are nonces used for form submissions? -- [ ] Are there any potential SQL injection vulnerabilities? -- [ ] Are there any potential XSS vulnerabilities? +* [ ] Is user input properly validated and sanitized? +* [ ] Is output properly escaped? +* [ ] Are capability checks used for user actions? +* [ ] Are nonces used for form submissions? +* [ ] Are there any potential SQL injection vulnerabilities? +* [ ] Are there any potential XSS vulnerabilities? ### Performance -- [ ] Are there any performance bottlenecks? -- [ ] Are database queries optimized? -- [ ] Is caching used appropriately? -- [ ] Are assets (CSS, JS) properly enqueued? +* [ ] Are there any performance bottlenecks? +* [ ] Are database queries optimized? +* [ ] Is caching used appropriately? +* [ ] Are assets (CSS, JS) properly enqueued? ### Compatibility -- [ ] Is the code compatible with the minimum supported WordPress version (5.0)? -- [ ] Is the code compatible with the minimum supported PHP version (7.0)? -- [ ] Are there any browser compatibility issues? -- [ ] Are there any conflicts with other plugins? +* [ ] Is the code compatible with the minimum supported WordPress version (5.0)? +* [ ] Is the code compatible with the minimum supported PHP version (7.0)? +* [ ] Are there any browser compatibility issues? +* [ ] Are there any conflicts with other plugins? ### Internationalization -- [ ] Are all user-facing strings translatable? -- [ ] Is the correct text domain used? -- [ ] Are translation functions used correctly? +* [ ] Are all user-facing strings translatable? +* [ ] Is the correct text domain used? +* [ ] Are translation functions used correctly? ### Accessibility -- [ ] Does the code follow accessibility best practices? -- [ ] Are ARIA attributes used appropriately? -- [ ] Is keyboard navigation supported? -- [ ] Is screen reader support implemented? +* [ ] Does the code follow accessibility best practices? +* [ ] Are ARIA attributes used appropriately? +* [ ] Is keyboard navigation supported? +* [ ] Is screen reader support implemented? ## Automated Code Review Tools @@ -65,33 +65,33 @@ This project uses several automated code review tools to maintain high code qual [CodeRabbit](https://www.coderabbit.ai/) is an AI-powered code review tool that provides automated feedback on pull requests. -- **Integration**: Add the CodeRabbit GitHub App to your repository -- **Benefits**: Provides AI-powered code reviews, identifies potential issues, and suggests improvements -- **Usage**: CodeRabbit automatically reviews pull requests when they are created or updated +* **Integration**: Add the CodeRabbit GitHub App to your repository +* **Benefits**: Provides AI-powered code reviews, identifies potential issues, and suggests improvements +* **Usage**: CodeRabbit automatically reviews pull requests when they are created or updated ### 2. CodeFactor [CodeFactor](https://www.codefactor.io/) continuously monitors code quality and provides feedback on code style, complexity, and potential issues. -- **Integration**: Add the CodeFactor GitHub App to your repository -- **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time -- **Usage**: CodeFactor automatically analyzes your codebase and provides feedback on pull requests +* **Integration**: Add the CodeFactor GitHub App to your repository +* **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time +* **Usage**: CodeFactor automatically analyzes your codebase and provides feedback on pull requests ### 3. Codacy [Codacy](https://www.codacy.com/) is a code quality tool that provides static analysis, code coverage, and code duplication detection. -- **Integration**: Add the Codacy GitHub App to your repository -- **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time -- **Usage**: Codacy automatically analyzes your codebase and provides feedback on pull requests +* **Integration**: Add the Codacy GitHub App to your repository +* **Benefits**: Provides a grade for your codebase, identifies issues, and tracks code quality over time +* **Usage**: Codacy automatically analyzes your codebase and provides feedback on pull requests ### 4. SonarCloud [SonarCloud](https://sonarcloud.io/) is a cloud-based code quality and security service that performs static code analysis to detect bugs, vulnerabilities, and code smells. -- **Integration**: Add the SonarCloud GitHub App to your repository -- **Benefits**: Provides detailed analysis of code quality, security vulnerabilities, and technical debt -- **Usage**: SonarCloud automatically analyzes your codebase and provides feedback on pull requests +* **Integration**: Add the SonarCloud GitHub App to your repository +* **Benefits**: Provides detailed analysis of code quality, security vulnerabilities, and technical debt +* **Usage**: SonarCloud automatically analyzes your codebase and provides feedback on pull requests ### Using AI Assistants with Code Review Tools @@ -103,6 +103,16 @@ When you receive feedback from these code review tools, you can use AI assistant 4. Implement the suggested fixes 5. Commit the changes and verify that the issues are resolved +### Markdown Formatting Standards + +When writing or updating Markdown files in this project, follow these standards: + +* Always use asterisks (*) for bullet points, not hyphens (-) +* Use proper heading hierarchy (# for main title, ## for sections, etc.) +* Use code blocks with language specification for code examples +* Use relative links for internal documentation +* Include alt text for images + Example prompt for AI assistants: ``` @@ -117,9 +127,9 @@ I received the following feedback from [Tool Name]. Please help me understand th Before reviewing code, understand: -- What problem is the code trying to solve? -- What are the requirements? -- What are the constraints? +* What problem is the code trying to solve? +* What are the requirements? +* What are the constraints? ### 2. Review the Code @@ -129,54 +139,54 @@ Review the code with the checklist above in mind. When providing feedback: -- Be specific and clear -- Explain why a change is needed -- Provide examples or suggestions when possible -- Prioritize feedback (critical issues vs. minor improvements) -- Be constructive and respectful +* Be specific and clear +* Explain why a change is needed +* Provide examples or suggestions when possible +* Prioritize feedback (critical issues vs. minor improvements) +* Be constructive and respectful ### 4. Follow Up After the code has been updated: -- Review the changes -- Verify that issues have been addressed -- Provide additional feedback if necessary +* Review the changes +* Verify that issues have been addressed +* Provide additional feedback if necessary ## Common Issues to Look For ### PHP Issues -- Undefined variables or functions -- Incorrect function parameters -- Missing return statements -- Improper error handling -- Inefficient loops or conditionals -- Hardcoded values that should be configurable +* Undefined variables or functions +* Incorrect function parameters +* Missing return statements +* Improper error handling +* Inefficient loops or conditionals +* Hardcoded values that should be configurable ### WordPress-Specific Issues -- Incorrect hook usage -- Missing or incorrect nonces -- Missing capability checks -- Direct database queries instead of using WordPress functions -- Improper enqueuing of scripts and styles -- Not using WordPress functions for common tasks +* Incorrect hook usage +* Missing or incorrect nonces +* Missing capability checks +* Direct database queries instead of using WordPress functions +* Improper enqueuing of scripts and styles +* Not using WordPress functions for common tasks ### JavaScript Issues -- Undefined variables or functions -- Event listener memory leaks -- jQuery conflicts -- Browser compatibility issues -- Missing error handling +* Undefined variables or functions +* Event listener memory leaks +* jQuery conflicts +* Browser compatibility issues +* Missing error handling ### CSS Issues -- Browser compatibility issues -- Specificity issues -- Unused styles -- Overriding WordPress admin styles inappropriately +* Browser compatibility issues +* Specificity issues +* Unused styles +* Overriding WordPress admin styles inappropriately ## Example Feedback diff --git a/.wiki/Coding-Standards.md b/.wiki/Coding-Standards.md index 7024ca7..ed60a65 100644 --- a/.wiki/Coding-Standards.md +++ b/.wiki/Coding-Standards.md @@ -8,40 +8,40 @@ This plugin follows the [WordPress Coding Standards](https://developer.wordpress ### File Structure -- Each PHP file should begin with the PHP opening tag `