wpallstars/wp-plugin-starter-template-for-ai-coding
Template
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rename .ai-assistant.md to AGENTS.md and .ai-workflows to .agents

Browse Source
This commit is contained in:
Marcus Quinn
2025-11-24 00:16:56 +00:00
parent 136f07d9c4
commit 6300b687aa
29 changed files with 48 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
.agents/bug-fixing.md Normal file
View File

@@ -0,0 +1,202 @@
# Bug Fixing Guide for AI Assistants
This document provides guidance for AI assistants to help with bug fixing for the Fix Plugin Does Not Exist Notices plugin.
## Bug Fixing Workflow
### 1. Create a Bug Fix Branch
Always start by creating a bug fix branch from the latest main branch pulled from origin (this step is mandatory):
```bash
git checkout main
git pull origin main # Critical step - never skip this
git checkout -b fix/bug-description
```
Use a descriptive name that clearly indicates what bug is being fixed. If there's an issue number, include it in the branch name (e.g., `fix/123-plugin-activation-error`).
For more detailed git workflow guidelines, see **@.ai-workflows/git-workflow.md**.
### 2. Understand the Bug
Before fixing a bug, make sure you understand:
- What is the expected behavior?
- What is the actual behavior?
- What are the steps to reproduce the bug?
- What is the impact of the bug?
- What is the root cause of the bug?
### 3. Fix the Bug
When fixing a bug:
- Make minimal changes necessary to fix the bug
- Avoid introducing new features while fixing bugs
- Maintain backward compatibility
- Add appropriate comments explaining the fix
- Consider adding tests to prevent regression
### 4. Update Documentation
Update relevant documentation to reflect the bug fix:
- Add a description to CHANGELOG.md under an "Unreleased" section
- Update readme.txt if the bug fix affects user-facing functionality
### 5. Testing
Test the bug fix thoroughly:
- Verify that the bug is fixed
- Ensure no regression in related functionality
- Test with the latest WordPress version
- Test with the minimum supported WordPress version (5.0)
- Test with PHP 7.0+ (minimum supported version)
### 6. Commit Changes
Make atomic commits with clear messages:
```bash
git add .
git commit -m "Fix #123: Brief description of the bug fix"
```
If there's an issue number, reference it in the commit message.
### 7. Prepare for Release
When the bug fix is ready to be released:
1. Create a version branch for the release:
```bash
git checkout -b v{MAJOR}.{MINOR}.{PATCH}
```
2. Merge your bug fix branch into the version branch:
```bash
git merge fix/bug-description --no-ff
```
3. Update version numbers and changelog entries
4. Follow the standard release process from this point
### 8. Push to Remote (Optional for Collaboration)
If you need to collaborate with others on the bug fix before it's ready for release:
```bash
git push github HEAD:fix/bug-description
git push gitea HEAD:fix/bug-description
```
### 9. Create Pull Request (Optional)
If the repository uses pull requests for code review, create a pull request from the bug fix branch to the version branch.
## Determining Version Increment
After fixing a bug and confirming it works, determine the appropriate version increment:
- **PATCH** (e.g., 1.6.0 → 1.6.1): For most bug fixes that don't change functionality
- **MINOR** (e.g., 1.6.0 → 1.7.0): For bug fixes that introduce new features or significant changes
- **MAJOR** (e.g., 1.6.0 → 2.0.0): For bug fixes that introduce breaking changes
**IMPORTANT**: Don't update version numbers during initial development and testing. Only create a version branch (e.g., `v2.2.3`) and update version numbers when the fix is confirmed working.
This approach is more time-efficient as it allows you to focus on fixing the bug without worrying about version updates until the fix is confirmed working.
For detailed guidelines on time-efficient development and testing, see **@.ai-workflows/incremental-development.md**.
## Testing Previous Versions
To test a previous version of the plugin:
```bash
# Checkout a specific tag for testing
git checkout v{MAJOR}.{MINOR}.{PATCH}
# Or create a test branch from a specific tag
git checkout v{MAJOR}.{MINOR}.{PATCH} -b test/some-feature
```
## Hotfix Process
For critical bugs that need immediate fixing in a released version:
### 1. Create a Hotfix Branch
```bash
git checkout v{MAJOR}.{MINOR}.{PATCH}
git checkout -b hotfix/v{MAJOR}.{MINOR}.{PATCH+1}
```
### 2. Fix the Issues
Apply the minimal fix necessary to address the critical issue.
### 3. Update Version Numbers
Increment the PATCH version and update all version numbers:
- Main plugin file (fix-plugin-does-not-exist-notices.php)
- FPDEN_VERSION constant
- CHANGELOG.md
- readme.txt
- README.md
- languages/fix-plugin-does-not-exist-notices.pot (Project-Id-Version)
### 4. Commit and Push
```bash
git add .
git commit -m "Hotfix: Brief description of the critical bug fix"
git push github HEAD:hotfix/v{MAJOR}.{MINOR}.{PATCH+1}
git push gitea HEAD:hotfix/v{MAJOR}.{MINOR}.{PATCH+1}
```
### 5. Create and Push Tag
```bash
git tag -a v{MAJOR}.{MINOR}.{PATCH+1} -m "Hotfix release version {MAJOR}.{MINOR}.{PATCH+1}"
git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH+1}
git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH+1}
```
## Common Bug Types and Fixing Strategies
### WordPress Compatibility Issues
- Test with the specific WordPress version where the issue occurs
- Check for deprecated functions or hooks
- Review WordPress changelog for relevant changes
### PHP Compatibility Issues
- Test with the specific PHP version where the issue occurs
- Check for deprecated PHP functions or features
- Use appropriate polyfills if necessary
### JavaScript Issues
- Test in different browsers
- Check for browser console errors
- Consider browser-specific workarounds if necessary
### CSS Issues
- Test in different browsers and screen sizes
- Use browser developer tools to inspect elements
- Consider browser-specific workarounds if necessary
### Database Issues
- Use proper database prefixing
- Sanitize database inputs
- Use prepared statements for queries
- Consider database version differences

154
.agents/code-quality-checks.md Normal file
View File

@@ -0,0 +1,154 @@
# Code Quality Checks Workflow
## Scope
This document is intended for plugin developers and code reviewers working on this repository. It outlines the process for ensuring code quality before pushing changes to the repository. Following these steps will help catch issues early and save time in the review process.
## Pre-Push Checklist
Before pushing your changes to the repository, run through the following checks:
1. **Run Unit Tests**
```bash
composer test
```
Ensure all tests pass. If any tests fail, resolve the issues before proceeding.
2. **Run PHP CodeSniffer**
```bash
composer phpcs
```
This will check your code against WordPress coding standards. Fix any issues before proceeding.
3. **Run PHP Code Beautifier and Fixer**
```bash
composer phpcbf
```
This will automatically fix many coding standard issues.
4. **Run PHPStan**
```bash
composer phpstan
```
This will perform static analysis on your code to find potential bugs and issues.
5. **Run PHP Mess Detector**
```bash
composer phpmd
```
This will check for potential problems like unused variables, empty catch blocks, etc.
## Common Issues and How to Fix Them
### 1. Inline Comments
All inline comments must end with proper punctuation (period, exclamation mark, or question mark).
```php
// Incorrect comment
$var = true;
// Correct comment.
$var = true;
```
### 2. Superglobal Access
Never access superglobals like `$_GET`, `$_POST`, etc. directly. Always use WordPress functions to sanitize and validate input.
```php
// Incorrect
$page = $_GET['page'];
// Correct
$page = filter_input(INPUT_GET, 'page', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
// For testing environments
if (defined('PHPUNIT_RUNNING') && PHPUNIT_RUNNING) {
// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- This rule is ignored in tests to allow direct access for testing purposes
$page = isset($_GET['page']) ? wp_unslash($_GET['page']) : '';
}
```
### 3. Avoid Unnecessary Else Clauses
Simplify your code by avoiding unnecessary else clauses.
```php
// Less preferred
if (condition) {
return true;
} else {
return false;
}
// Preferred
if (condition) {
return true;
}
return false;
```
### 4. Proper Function Spacing
Ensure proper spacing in function calls and declarations.
```php
// Incorrect
function_name($param1,$param2);
// Correct
function_name( $param1, $param2 );
```
### 5. Naming Conventions
Follow WordPress naming conventions:
* Functions and variables: snake_case with plugin-specific prefix (e.g., `myplugin_function_name`)
* Classes: CamelCase
* Constants: UPPERCASE_WITH_UNDERSCORES with plugin-specific prefix (e.g., `MYPLUGIN_CONSTANT_NAME`)
## Automated Checks in CI/CD
Our CI/CD pipeline includes the following automated checks:
1. **CodeFactor**: Analyzes code quality and style
2. **Codacy**: Performs static code analysis
3. **SonarCloud**: Checks for code smells, bugs, and security vulnerabilities
4. **CodeRabbit**: Provides AI-powered code review
Although CI runs these checks, catching issues locally helps save time and minimize follow-up commits.
## Using AI to Help with Code Quality
You can use AI assistants to help improve code quality:
1. Run the code quality checks locally
2. If issues are found, ask the AI assistant to help fix them
3. Apply the suggested fixes
4. Run the checks again to verify the issues are resolved
Example prompt:
```text
I ran PHPCS and got the following errors. Can you help me fix them?
[Paste error output here]
```
For more AI assistance guidelines, see the [AI Assistant Guide](./../.ai-assistant.md).
## Conclusion
This workflow helps maintain high code quality and accelerates the review process. Remember, it's always more efficient to resolve issues locally than to go through multiple rounds of CI/CD and code review.

240
.agents/code-review.md Normal file
View File

@@ -0,0 +1,240 @@
# Code Review Guide for AI Assistants
This document provides guidance for AI assistants to help with code review for this project.
## Code Review Checklist
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?
### 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?
### 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?
### Performance
* [ ] 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?
### Internationalization
* [ ] 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?
## Automated Code Review Tools
This project uses several automated code review tools to maintain high code quality standards. These tools are free to use for public repositories and should be integrated into any new repositories based on this template.
**Important**: Before pushing your code, run the local code quality checks as described in the [Code Quality Checks Workflow](./code-quality-checks.md) to catch issues early.
### 1. CodeRabbit
[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
### 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
### 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
### 4. PHPStan
[PHPStan](https://phpstan.org/) is a static analysis tool that finds errors in your code without running it.
* **Integration**: Included in the project's composer.json and GitHub Actions workflow
* **Benefits**: Detects undefined variables, methods, and properties; type-related issues; and logical errors
* **Usage**: Run `composer phpstan` or `npm run lint:phpstan` locally, or let GitHub Actions run it automatically
### 5. PHP Mess Detector
[PHP Mess Detector](https://phpmd.org/) is a tool that looks for potential problems in your code such as possible bugs, suboptimal code, overcomplicated expressions, and unused parameters, variables, and methods.
* **Integration**: Included in the project's composer.json and GitHub Actions workflow
* **Benefits**: Identifies code smells, complexity issues, unused code, naming problems, and more
* **Usage**: Run `composer phpmd` or `npm run lint:phpmd` locally, or let GitHub Actions run it automatically
### Using AI Assistants with Code Review Tools
When you receive feedback from these code review tools, you can use AI assistants to help address the issues:
1. Copy the output from the code review tool
2. Paste it into your AI assistant chat
3. Ask the AI to help you understand and resolve the issues
4. Apply 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:
```text
I received the following feedback from [Tool Name]. Please help me understand and resolve these issues:
[Paste the tool output here]
```
## Code Review Process
### 1. Understand the Context
Before reviewing code, understand:
* What problem is the code trying to solve?
* What are the requirements?
* What are the constraints?
### 2. Review the Code
Review the code with the checklist above in mind.
### 3. Provide Feedback
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
### 4. Follow Up
After the code has been updated:
* 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
### 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
### JavaScript Issues
* 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
## Example Feedback
### Good Feedback Example
```markdown
In function `handle_remove_reference()`:
1. The nonce check is missing, which could lead to CSRF vulnerabilities.
Consider adding:
```php
if (!isset($_GET['_wpnonce']) || !wp_verify_nonce($_GET['_wpnonce'], 'fpden_remove_reference')) {
wp_die(__('Security check failed.', 'fix-plugin-does-not-exist-notices'));
}
```
2. The user capability check should be more specific. Instead of:
```php
if (!current_user_can('manage_options')) {
```
Consider using:
```php
if (!current_user_can('activate_plugins')) {
```
This is more appropriate for the action being performed.
3. The success message should be translatable:
```php
// Change this:
add_settings_error('fpden', 'fpden_removed', 'Plugin reference removed successfully.', 'updated');
// To this:
add_settings_error('fpden', 'fpden_removed', __('Plugin reference removed successfully.', 'fix-plugin-does-not-exist-notices'), 'updated');
```
```
### Poor Feedback Example
```text
This code has security issues and doesn't follow best practices. Fix it.
```

62
.agents/dev-prefs-memory.md Normal file
View File

@@ -0,0 +1,62 @@
# Developer Preferences Memory
This document serves as a persistent memory for developer preferences established during coding sessions. AI assistants should refer to this document to understand the developer's preferences and update it as new preferences are established.
## Purpose
- Maintain a consistent record of developer preferences across coding sessions
- Ensure AI assistants can provide assistance that aligns with the developer's preferred coding style and practices
- Reduce the need for developers to repeatedly explain their preferences
## How to Use This Document
- **AI Assistants**: Review this document before providing assistance. Update it when new preferences are established through user feedback.
- **Developers**: Reference this document to see what preferences have been recorded. Feel free to edit it directly to add or modify preferences.
## Recorded Preferences
### File and Directory Structure
- Prefer lowercase filenames for consistency across the codebase
- Use unique folder names following best practices
- Folder references should be easily identifiable when using @mentions in AI-assisted coding
- Admin-specific functionality should be in the `admin/lib/` directory
- Core plugin functionality should be in the `includes/` directory
### Code Style
- Follow WordPress coding standards
- Use OOP best practices for WordPress plugins
- Create modular, maintainable, and efficient code structure
### Documentation
- Prefer token-efficient documentation in `.ai-assistant.md` that references `.ai-workflows/` files
- Document the release workflow in `.ai-assistant.md` and `.ai-workflows/release-process.md`
- Store environment variable documentation in `.ai-workflows/local-env-vars.md`
- Maintain consistent documentation across readme.txt, README.md, and CHANGELOG.md
### Asset Organization
- Store banner, icon, and screenshot images in `.wordpress-org/assets/`
- Store WORDPRESS_ORG files within `/wordpress-org`
- Organize files in `/assets` into relevant `/admin` folders
### Version Control
- Use standard Git practices for version control and code management
- When updating plugin versions, create a GitHub tag and trigger GitHub actions
- Follow a specific release process with proper tagging and GitHub releases
- Ensure commits are merged to the main branch as Git Updater pulls data from the readme.txt file in the primary branch
### Plugin Development
- Prefer simpler solutions over complex ones for plugins
- Use a specific formatting style for the CHANGELOG.md file, using #### for section headings
- When updating plugin versions, remember to update language files (POT/PO)
- Comment out redundant code during testing
### Potential AI Assised IDE Issues
- Check for non-standard local terminal commandline customisations that might not be understood by the AI IDE in its terminal useage and cause errors in execution or confusion in not seeing expected results, and advise on how to resolve
- Check for non-standard or multiple python and node.js versions, including homebrew versions, that might not be understood by the AI IDE in its terminal useage and cause errors in execution or confusion in not seeing expected results, and advise on how to resolve

205
.agents/feature-development.md Normal file
View File

@@ -0,0 +1,205 @@
# Feature Development Guide for AI Assistants
This document provides guidance for AI assistants to help with feature development for the Fix Plugin Does Not Exist Notices plugin.
## Feature Development Workflow
### 1. Create a Feature Branch
Always start by creating a feature branch from the latest main branch pulled from origin (this step is mandatory):
```bash
git checkout main
git pull origin main # Critical step - never skip this
git checkout -b feature/descriptive-name
```
Use a descriptive name that clearly indicates what the feature is about. If there's an issue number, include it in the branch name (e.g., `feature/123-update-source-selector`).
For more detailed git workflow guidelines, see **@.ai-workflows/git-workflow.md**.
### 2. Implement the Feature
When implementing a new feature:
- Follow WordPress coding standards
- Ensure all strings are translatable
- Add appropriate comments
- Consider performance implications
- Maintain backward compatibility
- Review reference plugins in the `reference-plugins/` directory for inspiration and best practices
### 3. Update Documentation
Update relevant documentation to reflect the new feature:
- Add a description to CHANGELOG.md under an "Unreleased" section
- Update readme.txt if the feature affects user-facing functionality
- Update README.md with the new feature description
- Update inline documentation/comments
- Update wiki documentation in the `.wiki` directory:
- Create or update feature-specific pages
- Update the Home.md page if necessary
- Add the feature to any relevant existing pages
- Add screenshots or examples if applicable
- Remember that any feature addition will require a version increment in all relevant files
For detailed guidelines on maintaining wiki documentation, see **@.ai-workflows/wiki-documentation.md**.
### 4. Testing
Test the feature thoroughly:
- Test with the latest WordPress version
- Test with the minimum supported WordPress version (5.0)
- Test with PHP 7.0+ (minimum supported version)
- Test in different environments (if possible)
### 5. Commit Changes
Make atomic commits with clear messages:
```bash
git add .
git commit -m "Add feature: descriptive name"
```
### 6. Prepare for Release
When the feature is ready to be released:
1. Create a version branch with the appropriate version number (typically increment the minor version for features):
```bash
# Example: from 2.2.0 to 2.3.0
git checkout -b v{MAJOR}.{MINOR+1}.0
```
2. Now update version numbers in all required files:
- Main plugin file (wp-fix-plugin-does-not-exist-notices.php)
- CHANGELOG.md (add a new version section)
- readme.txt
- README.md
- languages/wp-fix-plugin-does-not-exist-notices.pot (Project-Id-Version)
3. Commit the version updates:
```bash
git add .
git commit -m "Version {MAJOR}.{MINOR+1}.0 - [brief description]"
```
4. Tag the version as stable:
```bash
git tag -a v{MAJOR}.{MINOR+1}.0-stable -m "Stable version {MAJOR}.{MINOR+1}.0"
```
5. Follow the standard release process from this point
**IMPORTANT**: Don't update version numbers during initial development and testing. Only create a version branch and update version numbers when the feature is confirmed working.
For detailed guidelines on time-efficient development and testing, see **@.ai-workflows/incremental-development.md**.
### 7. Push to Remote (Optional for Collaboration)
If you need to collaborate with others on the feature before it's ready for release:
```bash
git push github HEAD:feature/descriptive-name
git push gitea HEAD:feature/descriptive-name
```
### 8. Create Pull Request (Optional)
If the repository uses pull requests for code review, create a pull request from the feature branch to the version branch.
## Code Standards and Best Practices
### PHP Coding Standards
- Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
- Use tabs for indentation, not spaces
- Use proper naming conventions:
- Class names: `Class_Name`
- Function names: `function_name`
- Variable names: `$variable_name`
### JavaScript Coding Standards
- Follow [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/)
- Use tabs for indentation, not spaces
- Use proper naming conventions:
- Function names: `functionName`
- Variable names: `variableName`
### Internationalization (i18n)
- Wrap all user-facing strings in appropriate translation functions:
- `__()` for simple strings
- `_e()` for echoed strings
- `esc_html__()` for escaped strings
- `esc_html_e()` for escaped and echoed strings
- Always use the plugin's text domain: `fix-plugin-does-not-exist-notices`
### Security Best Practices
- Validate and sanitize all input
- Escape all output
- Use nonces for form submissions
- Use capability checks for user actions
## Working in Multi-Repository Workspaces
When developing features in a workspace with multiple repositories:
1. **Verify Repository Context**:
- Confirm you're working in the correct repository before suggesting or implementing features
- Use `pwd` and `git remote -v` to verify the current repository
2. **Feature Verification**:
- Before implementing a feature, verify it doesn't already exist in the current repository
- Don't assume features from other repositories should be implemented in this one
- Use `codebase-retrieval` to search for existing functionality
3. **Repository-Specific Implementation**:
- Implement features appropriate for this specific plugin's purpose
- Maintain consistency with the current repository's architecture and coding style
- Don't copy code directly from other repositories without adaptation
4. **Cross-Repository Inspiration**:
- If implementing a feature inspired by another repository, explicitly note that it's a new feature
- Adapt the feature to fit the current repository's needs and architecture
- Document the inspiration source in code comments
For detailed guidelines on working in multi-repository workspaces, see **@.ai-workflows/multi-repo-workspace.md**.
## Feature Types and Implementation Guidelines
### Admin Interface Features
When adding features to the admin interface:
- Use WordPress admin UI components for consistency
- Follow WordPress admin UI patterns
- Ensure accessibility compliance
- Add appropriate help text
### Plugin Functionality Features
When adding core functionality:
- Ensure compatibility with WordPress hooks system
- Consider performance impact
- Maintain backward compatibility
- Add appropriate error handling
### Integration Features
When adding integration with other plugins or services:
- Make integrations optional when possible
- Check if the integrated plugin/service is available before using it
- Provide fallback functionality when the integration is not available
- Document the integration requirements

59
.agents/folder-structure.md Normal file
View File

@@ -0,0 +1,59 @@
# Folder Structure
This document outlines the folder structure of the plugin and explains the purpose of each directory.
## Root Directories
- **admin/** - Contains admin-specific functionality and assets
- **includes/** - Contains core plugin functionality and classes
- **languages/** - Contains translation files
- **scripts/** - Contains build and deployment scripts
- **.ai-workflows/** - Contains documentation for AI assistants
- **.github/** - Contains GitHub-specific files like workflows
- **.wordpress-org/** - Contains WordPress.org assets like banners and screenshots
## Admin Directory Structure
- **admin/css/** - Admin-specific CSS files
- **admin/js/** - Admin-specific JavaScript files
- **admin/images/** - Admin-specific images
- **admin/partials/** - Admin-specific template partials
- **admin/settings/** - Admin settings functionality
- **admin/tools/** - Admin tools functionality
- **admin/lib/** - Admin-specific library files and helper functions
- **admin/lib/admin.php** - Admin class for handling admin-specific functionality
- **admin/lib/modal.php** - Modal class for handling the update source selector modal
## Includes Directory
The `includes/` directory contains the core plugin functionality:
- **includes/core.php** - Core class for handling the main plugin functionality
- **includes/plugin.php** - Main plugin class that initializes all components
- **includes/updater.php** - Updater class for handling plugin updates
## File Naming Conventions
- All PHP files in the `includes/` directory use lowercase filenames
- All directories use lowercase names
- JavaScript and CSS files use kebab-case (e.g., `update-source-selector.js`)
## Best Practices
1. **Unique Directory Names**: Each directory should have a unique name to avoid confusion
2. **Logical Organization**: Files should be organized logically by function
3. **Consistent Naming**: File and directory names should follow consistent naming conventions
4. **Clear Separation**: Admin functionality should be separate from core functionality
5. **Minimal Dependencies**: Files should have minimal dependencies on other files
## @mentions for AI Assistants
When referring to files or directories in AI conversations, use the following format:
- **@includes/plugin.php** - Main plugin class
- **@includes/core.php** - Core functionality
- **@admin/lib/admin.php** - Admin functionality
- **@admin/lib/modal.php** - Modal functionality
- **@includes/updater.php** - Updater functionality
- **@admin/js/update-source-selector.js** - Update source selector JavaScript
- **@admin/css/update-source-selector.css** - Update source selector CSS

255
.agents/git-workflow.md Normal file
View File

@@ -0,0 +1,255 @@
# Git Workflow Guide for AI Assistants
This document provides guidance for AI assistants to help with git workflow management for the Fix Plugin Does Not Exist Notices plugin.
## Core Git Workflow Principles
### 1. Always Start from Latest Main Branch
Before creating any new branch, always ensure you're working with the latest code from the main branch by pulling from the origin:
```bash
git checkout main
git pull origin main
```
This critical step ensures that your new branch includes all the latest changes from the remote repository and reduces the chance of merge conflicts later. Never skip this step, as working from an outdated main branch can lead to integration problems.
### 2. One Issue Per Branch
Create a separate branch for each issue or feature you're working on:
- For bug fixes: `fix/issue-description` or `fix/issue-number-description`
- For features: `feature/descriptive-name`
- For small improvements: `patch/descriptive-name`
- For code restructuring: `refactor/descriptive-name`
**Important**: Use descriptive names without version numbers for development branches. This allows focusing on the changes without worrying about version updates until the changes are confirmed working.
Only create version branches (e.g., `v2.2.3`) when changes are ready for release, and only then update version numbers in files.
This approach keeps changes focused, makes code review easier, and provides clear rollback points if needed.
### 3. Pull Request for Each Issue
Create a separate pull request for each issue or feature. This ensures:
- Each change can be reviewed independently
- Issues can be merged as soon as they're ready
- Changes can be reverted individually if needed
- CI/CD checks can run on focused changes
## Detailed Workflow
### Starting a New Task
1. **Update Main Branch from Origin**
```bash
git checkout main
git pull origin main
```
This step is mandatory before creating any new branch to ensure you're working with the latest code.
2. **Create a New Branch**
```bash
git checkout -b [branch-type]/[description]
```
Examples:
```bash
git checkout -b fix/123-plugin-activation-error
git checkout -b feature/update-source-selector
git checkout -b patch/2.2.1
```
3. **Make Your Changes**
- Make focused changes related only to the specific issue
- Commit regularly with clear, descriptive messages
- Reference issue numbers in commit messages when applicable
4. **Testing Approach**
For efficient development:
- **Local Testing (Default)**: Test without updating version numbers
```bash
# Get current version from plugin file
CURRENT_VERSION=$(grep -o "Version: [0-9.]*" wp-fix-plugin-does-not-exist-notices.php | cut -d' ' -f2)
# Build and deploy with current version
./build.sh $CURRENT_VERSION
```
- **Remote Testing (When Requested)**: Push development branch to remote
```bash
git add .
git commit -m "[Brief description] for remote testing"
git push origin [branch-name]
```
- **Version Creation**: Only when changes are confirmed working
```bash
# Create version branch
git checkout -b v{MAJOR}.{MINOR}.{PATCH}
# Update version numbers in all required files
# Commit version updates
git add .
git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - Brief description"
# Tag as stable
git tag -a v{MAJOR}.{MINOR}.{PATCH}-stable -m "Stable version {MAJOR}.{MINOR}.{PATCH}"
```
5. **Push Branch to Remote (When Needed)**
```bash
git push origin [branch-name]
```
### Creating a Pull Request
1. **Ensure Tests Pass Locally**
- Run any available tests to ensure your changes work as expected
- Fix any issues before creating a pull request
2. **Create Pull Request**
- Create a pull request from your branch to the main branch
- Include a clear description of the changes
- Reference any related issues
- Assign reviewers if appropriate
3. **Address Review Feedback**
- Make requested changes
- Push additional commits to the same branch
- Respond to comments
### CI/CD Integration
Each pull request should pass through CI/CD checks before being merged. This ensures that all changes are compatible with the existing codebase and meet quality standards.
1. **Automated Tests**
- Unit tests
- Integration tests
- Code style checks
- Compatibility checks
2. **Manual Review**
- Code review by team members
- Functional testing in test environment
- Verification of feature requirements
3. **Approval Process**
- Required approvals before merging
- Final checks for conflicts with other pending PRs
- Verification that all CI/CD checks have passed
4. **Compatibility with Unmerged PRs**
- When multiple PRs are in progress simultaneously, ensure each PR is compatible with the main branch
- For related changes, consider using feature flags to allow independent merging
- Document dependencies between PRs in the PR description
### Handling Concurrent Development
When working on multiple issues simultaneously:
1. **Keep Branches Independent**
- Always create new branches from the latest main branch pulled from origin, not from other feature branches
- This ensures each PR can be merged independently and contains all the latest changes
2. **Handle Conflicts Proactively**
- If main has been updated with other changes while you're working:
```bash
git checkout main
git pull origin main
git checkout your-branch
git merge main
```
- Resolve any conflicts locally before pushing
3. **Coordinate on Dependent Changes**
- If changes depend on each other, note this in the PR description
- Consider using the "Depends on #PR-number" notation in PR descriptions
## Release Process
When preparing for a release:
1. **Ensure All Required PRs are Merged**
- All features and fixes planned for the release should be merged to main
2. **Create a Release Branch**
```bash
git checkout main
git pull origin main
git checkout -b v{MAJOR}.{MINOR}.{PATCH}
```
3. **Follow Standard Release Process**
- Update version numbers
- Update changelogs
- Create tag
- See **@.ai-workflows/release-process.md** for complete details
## Contributing to External Repositories
When working on issues for external repositories (pull/merge requests):
### 1. Clearly Indicate Testing Status
In the PR description and comments, clearly indicate the testing status:
- **Not tested**: "This PR addresses [issue] but has not been tested locally or remotely. It's ready for community/maintainer testing."
- **Locally tested**: "This PR has been tested in a local WordPress environment and [describe results]."
- **Remotely tested**: "This PR has been tested with a remote build and [describe results]."
### 2. Provide Testing Instructions
Include clear instructions for maintainers on how to test the changes:
- Steps to reproduce the original issue (if applicable)
- Steps to verify the fix or feature
- Any specific environments or configurations needed for testing
### 3. Be Responsive to Feedback
Monitor the PR for feedback from maintainers and be prepared to make additional changes if requested.
## Best Practices
### Commit Messages
- Use present tense ("Add feature" not "Added feature")
- Start with a verb
- Keep the first line under 50 characters
- Reference issues when relevant: "Fix #123: Resolve plugin detection issue"
- For more complex changes, add a detailed description after the first line
### Branch Management
- Delete branches after they've been merged
- Keep branch names descriptive but concise
- Use consistent naming conventions
### Code Review
- Review code thoroughly before approving
- Test changes locally when possible
- Provide constructive feedback
- See **@.ai-workflows/code-review.md** for detailed code review guidelines
### Suggested Improvements
If you identify potential improvements outside the scope of the current issue:
1. **Document the Suggestion**
- Note the suggestion in the PR comments
- Create a new issue for the suggestion
- Be specific about the benefits and implementation details
2. **Create a Separate Branch**
- Don't include unrelated improvements in the current PR
- Create a new branch from the latest main branch for the suggested improvement
- Submit a separate PR for the suggestion
3. **Ensure Compatibility**
- Make sure the suggested improvement is compatible with any unmerged PRs
- If the improvement depends on changes in another PR, note this dependency
- Consider how the improvement will interact with other pending changes

229
.agents/incremental-development.md Normal file
View File

@@ -0,0 +1,229 @@
# Incremental Development and Testing Guide
This document provides guidance for AI assistants to help with incremental development and testing for the Fix Plugin Does Not Exist Notices plugin.
## Time-Efficient Development Principles
### Branch Naming for Development
1. **Initial Development Branches**
- Use descriptive names without version numbers:
- `fix/issue-description` - For bug fixes
- `feature/descriptive-name` - For new features
- `patch/descriptive-name` - For small improvements
- `refactor/descriptive-name` - For code restructuring
- **Don't update version numbers** during this phase
- Focus on implementing and testing the changes
2. **Version Branches**
- Only create after changes are confirmed working:
- `v{MAJOR}.{MINOR}.{PATCH}` (e.g., `v2.2.3`)
- Only update version numbers at this point
- This minimizes unnecessary version updates
### Version Numbering Guidelines
1. **Patch Versions (X.Y.Z → X.Y.Z+1)**
- Use for bug fixes and small improvements
- Example: `v2.2.3`
2. **Minor Versions (X.Y.Z → X.Y+1.0)**
- Use for new features or significant improvements
- Example: `v2.3.0`
3. **Major Versions (X.Y.Z → X+1.0.0)**
- Only increment when numerous features and fixes are tested and confirmed stable
- Reserved for breaking changes or significant overhauls
- Example: `v3.0.0`
### Marking Stable Versions
When the user confirms that changes are working correctly:
1. Create a version branch and update version numbers
2. Tag the version branch as stable
```bash
git tag -a v{MAJOR}.{MINOR}.{PATCH}-stable -m "Stable version {MAJOR}.{MINOR}.{PATCH}"
```
3. Document in the PR or issue that this version has been confirmed stable
## Local Testing Workflow
### 1. Create a Descriptive Branch for Development
```bash
# Ensure you have the latest main branch
git checkout main
git pull origin main
# Create a descriptive branch (without version numbers)
git checkout -b fix/plugin-activation-error
```
### 2. Make Changes Without Updating Version Numbers
During the development and testing phase:
- Implement the necessary changes
- **Don't update version numbers** in any files yet
- Focus on the functionality
### 3. Build and Deploy Locally
For local testing, use the current version number from the main plugin file:
```bash
# Get the current version from the plugin file
CURRENT_VERSION=$(grep -o "Version: [0-9.]*" wp-fix-plugin-does-not-exist-notices.php | cut -d' ' -f2)
# Build and deploy with current version
./build.sh $CURRENT_VERSION
```
This will:
1. Create a build directory
2. Copy required files to the build directory
3. Deploy the plugin to your local WordPress testing environment
**Note**: For local testing iterations, you do not need to commit changes, push to remote repositories, or create tags unless specifically requested.
### 4. Test and Evaluate
Test the changes thoroughly in the local environment:
- Verify that the specific issue is fixed or feature works as expected
- Check for any regressions or new issues
- Document the results
### 5. Based on Testing Results
- **If changes need further refinement**: Continue working in the same branch
- **If changes work as expected**: Proceed to version branch creation
### 6. Creating a Version Branch
When changes are confirmed working and ready for release:
1. Create a version branch with the appropriate version number:
```bash
# Determine the appropriate version increment (patch, minor, or major)
# based on the nature of the changes
git checkout -b v{MAJOR}.{MINOR}.{PATCH}
```
2. Now update version numbers in all required files:
- Main plugin file (wp-fix-plugin-does-not-exist-notices.php)
- CHANGELOG.md (add a new version section)
- readme.txt
- README.md
- languages/wp-fix-plugin-does-not-exist-notices.pot (Project-Id-Version)
3. Commit the version updates:
```bash
git add .
git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - [brief description]"
```
4. Tag the version as stable:
```bash
git tag -a v{MAJOR}.{MINOR}.{PATCH}-stable -m "Stable version {MAJOR}.{MINOR}.{PATCH}"
```
## Remote Testing Workflow
When the user specifically requests remote testing:
### 1. Commit Changes to Remote Repository
If testing a development branch (without version updates):
```bash
git add .
git commit -m "[brief description] for remote testing"
git push origin [branch-name]
```
If testing a version branch (with version updates):
```bash
git add .
git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - [brief description]"
git push origin v{MAJOR}.{MINOR}.{PATCH}
```
### 2. Create and Push Tag (For Version Branches Only)
```bash
git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Version {MAJOR}.{MINOR}.{PATCH} for remote testing"
git push origin v{MAJOR}.{MINOR}.{PATCH}
```
This will trigger GitHub Actions to build the installable ZIP file.
### 3. Verify Remote Build
Check that the GitHub Actions workflow completed successfully and the ZIP file is available for download.
### 4. Test and Evaluate
Test the remotely built version and document the results.
## Contributing to External Repositories
When working on issues for external repositories (pull/merge requests):
### 1. Clearly Indicate Testing Status
In the PR description and comments, clearly indicate the testing status:
- **Not tested**: "This PR addresses [issue] but has not been tested locally or remotely. It's ready for community/maintainer testing."
- **Locally tested**: "This PR has been tested in a local WordPress environment and [describe results]."
- **Remotely tested**: "This PR has been tested with a remote build and [describe results]."
### 2. Provide Testing Instructions
Include clear instructions for maintainers on how to test the changes:
- Steps to reproduce the original issue (if applicable)
- Steps to verify the fix or feature
- Any specific environments or configurations needed for testing
### 3. Be Responsive to Feedback
Monitor the PR for feedback from maintainers and be prepared to make additional changes if requested.
## Rollback Procedure
If a change causes issues after release:
### 1. Identify the Last Stable Version
Find the last version that was marked as stable:
```bash
git tag -l "*-stable"
```
### 2. Create a New Branch from the Stable Version
```bash
git checkout v{MAJOR}.{MINOR}.{PATCH}-stable
git checkout -b fix/rollback-based-fix
```
### 3. Make Necessary Changes
Implement the fix based on the stable version. Don't update version numbers yet.
### 4. Test the Changes
Test thoroughly to ensure the fix resolves the issues.
### 5. When Confirmed Working
Create a version branch with an incremented patch version and update all version numbers as described in the "Creating a Version Branch" section.

22
.agents/local-env-vars.md Normal file
View File

@@ -0,0 +1,22 @@
# Local Development Environment Variables
This file contains important paths and URLs for local development.
## Repository Paths
- Local development repository: ~/Git/wp-fix-plugin-does-not-exist-notices
- LocalWP plugin testing site storage: ~/Local/plugin-testing/app/wp-fix-plugin-does-not-exist-notices
- LocalWP plugin testing site configuration: ~/Local/plugin-testing/conf/
## URLs
- LocalWP plugin testing URL: <http://plugin-testing.local/>
- PHP details: <http://plugin-testing.local/local-phpinfo.php>
- XDebug info: <http://plugin-testing.local/local-xdebuginfo.php>
- Adminer Evo: <http://localhost:10010/?username=root&db=local>
- Mailpit: <http://localhost:10000/>
## Build and Deploy Scripts
- Build script: ~/Git/wp-fix-plugin-does-not-exist-notices/build.sh
- Local deploy script: ~/Git/wp-fix-plugin-does-not-exist-notices/deploy-local.sh

124
.agents/multi-repo-workspace.md Normal file
View File

@@ -0,0 +1,124 @@
# Working in Multi-Repository Workspaces
This document provides guidelines for AI assistants working in VSCode/VSCodium workspaces that contain multiple repository folders.
## Understanding Multi-Repository Workspaces
In VSCode/VSCodium, developers often create workspaces that include multiple repository folders. This allows them to work on related projects simultaneously or reference code from one project while working on another.
### Common Workspace Configurations
1. **Multiple WordPress Plugins**: A workspace containing several WordPress plugin repositories
2. **Plugin and Theme Combinations**: Repositories for both plugins and themes that work together
3. **Reference Repositories**: Including repositories purely for reference or inspiration
4. **Shared Libraries**: Repositories containing shared code used across multiple projects
## Potential Issues in Multi-Repository Workspaces
### 1. Feature Hallucination
The most common issue is "feature hallucination" - assuming that features present in one repository should be implemented in another, or documenting non-existent features based on code seen in other repositories.
### 2. Cross-Repository Code References
Referencing or suggesting code patterns from one repository when working on another can lead to inconsistent coding styles and approaches.
### 3. Documentation Confusion
Creating documentation that includes features or functionality from other repositories in the workspace.
### 4. Scope Creep
Suggesting changes or improvements based on other repositories, leading to scope creep and feature bloat.
## Best Practices for AI Assistants
### 1. Repository Verification
**ALWAYS** verify which repository you're currently working in before:
- Making code suggestions
- Creating or updating documentation
- Discussing features or functionality
- Implementing new features
### 2. Explicit Code Search Scoping
When searching for code or functionality:
- Explicitly limit searches to the current repository
- Use repository-specific paths in search queries
- Verify search results are from the current repository before using them
### 3. Feature Verification Process
Before documenting or implementing a feature:
1. **Check the codebase**: Use the codebase-retrieval tool to search for relevant code in the current repository
2. **Verify functionality**: Look for actual implementation, not just references or comments
3. **Check documentation**: Review existing documentation to understand intended functionality
4. **Ask for clarification**: If uncertain, ask the developer to confirm the feature's existence or scope
### 4. Documentation Guidelines
When creating or updating documentation:
1. **Repository-specific content**: Only document features and functionality that exist in the current repository
2. **Verify before documenting**: Check the codebase to confirm features actually exist
3. **Clear boundaries**: Make it clear which repository the documentation applies to
4. **Accurate feature descriptions**: Describe features as they are implemented, not as they might be in other repositories
### 5. Cross-Repository Inspiration
When implementing features inspired by other repositories:
1. **Explicit attribution**: Clearly state that the feature is inspired by another repository
2. **New implementation**: Treat it as a new feature being added, not an existing one
3. **Repository-appropriate adaptation**: Adapt the feature to fit the current repository's architecture and style
4. **Developer confirmation**: Confirm with the developer that adding the feature is appropriate
## Repository Context Verification Checklist
Before making significant changes or recommendations, run through this checklist:
- [ ] Verified current working directory/repository
- [ ] Confirmed repository name and purpose
- [ ] Checked that code searches are limited to current repository
- [ ] Verified features exist in current repository before documenting them
- [ ] Ensured documentation reflects only the current repository's functionality
- [ ] Confirmed that any cross-repository inspiration is clearly marked as new functionality
## Example Verification Workflow
1. **Check current repository**:
```
pwd
git remote -v
```
2. **Verify feature existence**:
```
# Use codebase-retrieval to search for the feature
# Look for actual implementation, not just references
```
3. **Document with clear repository context**:
```
# Always include repository name in documentation
# Be specific about which features are included
```
4. **When suggesting new features**:
```
# Clearly state if inspired by another repository
# Explain why it's appropriate for the current repository
```
## Handling Repository Switching
When the developer switches between repositories in the workspace:
1. **Acknowledge the switch**: Confirm the new repository context
2. **Reset context**: Don't carry over assumptions from the previous repository
3. **Verify new environment**: Check the structure and features of the new repository
4. **Update documentation references**: Ensure you're referencing documentation specific to the new repository

19
.agents/readme.md Normal file
View File

@@ -0,0 +1,19 @@
# AI Workflows
This directory contains workflow documentation for AI assistants working with this repository.
## Contents
- **bug-fixing.md**: Guidelines for identifying and fixing bugs in the codebase
- **code-review.md**: Standards and procedures for reviewing code changes
- **dev-prefs-memory.md**: Persistent memory of developer preferences
- **feature-development.md**: Process for developing new features
- **folder-structure.md**: Documentation of the plugin's folder structure and naming conventions
- **git-workflow.md**: Detailed git workflow and branch management guidelines
- **incremental-development.md**: Time-efficient approach for incremental development and testing
- **local-env-vars.md**: Local development environment paths and URLs
- **multi-repo-workspace.md**: Guidelines for working in workspaces with multiple repositories
- **release-process.md**: Steps for preparing and publishing new releases
- **wiki-documentation.md**: Guidelines for maintaining wiki documentation
These documents help ensure consistent quality and approach when using AI tools to assist with development tasks.

207
.agents/release-process.md Normal file
View File

@@ -0,0 +1,207 @@
# Release Process Guide for AI Assistants
This document outlines the process for preparing and publishing new releases of the WordPress Plugin Starter Template.
## Release Workflow Overview
1. Create a version branch
2. Update version numbers in all required files
3. Run code quality checks
4. Build and test the plugin
5. Commit version changes
6. Create version tags
7. Push to remote repositories
8. Merge into main branch
## Detailed Steps
### 1. Create a Version Branch
Always start by creating a version branch from the latest main branch:
```bash
git checkout main
git pull origin main # Critical step - never skip this
git checkout -b v{MAJOR}.{MINOR}.{PATCH}
```
Example: `git checkout -b v1.0.0`
### 2. Update Version Numbers
Update version numbers in all required files:
1. **Main plugin file** (wp-plugin-starter-template.php):
- Update the `Version:` header
- Update the version parameter in the Plugin class instantiation
2. **readme.txt**:
- Update the `Stable tag:` value
- Add a new section to the changelog
3. **README.md**:
- Update version references
- Add new section to the changelog
4. **CHANGELOG.md**:
- Add a new version section at the top
5. **languages/wp-plugin-starter-template.pot**:
- Update the `Project-Id-Version` header
### 3. Run Code Quality Checks
Before building the plugin, run code quality checks to ensure the code meets standards:
```bash
# Run unit tests
composer test
# Run PHP CodeSniffer
composer phpcs
# Run PHP Code Beautifier and Fixer if needed
composer phpcbf
# Run PHPStan
composer phpstan
# Run PHP Mess Detector
composer phpmd
```
Fix any issues found by these tools before proceeding. See the [Code Quality Checks Workflow](./code-quality-checks.md) for more details.
### 4. Build and Test the Plugin
Build the plugin with the new version:
```bash
./build.sh {MAJOR}.{MINOR}.{PATCH}
```
This will:
- Create a clean build in the `build/` directory
- Generate a ZIP file for distribution
- Deploy to a local WordPress installation if configured
Test the plugin thoroughly:
- Test with the latest WordPress version
- Test with the minimum supported WordPress version (5.0)
- Test with PHP 7.0+ (minimum supported version)
- Test all features and functionality
### 5. Commit Version Changes
Commit all version changes:
```bash
git add wp-plugin-starter-template.php readme.txt README.md CHANGELOG.md languages/wp-plugin-starter-template.pot
git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - [brief description]"
```
### 6. Create Version Tags
Create version tags:
```bash
git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Version {MAJOR}.{MINOR}.{PATCH}"
git tag -a v{MAJOR}.{MINOR}.{PATCH}-stable -m "Stable version {MAJOR}.{MINOR}.{PATCH}"
```
The `-stable` tag is used by Git Updater to identify the stable version.
### 7. Push to Remote Repositories
Push the version branch and tags to remote repositories:
```bash
# List remote tags (replace 'github' and 'gitea' if your remotes have different names)
git ls-remote --tags github
git ls-remote --tags gitea
```
If the tags (e.g., `v{MAJOR}.{MINOR}.{PATCH}` and `v{MAJOR}.{MINOR}.{PATCH}-stable`) already exist remotely but point to the wrong commit, delete them from the remote first:
```bash
# Delete incorrect remote tags (replace 'github', 'gitea', and tag names)
git push github --delete v{MAJOR}.{MINOR}.{PATCH}
git push github --delete v{MAJOR}.{MINOR}.{PATCH}-stable
git push gitea --delete v{MAJOR}.{MINOR}.{PATCH}
git push gitea --delete v{MAJOR}.{MINOR}.{PATCH}-stable
```
Once you've confirmed the tags don't exist remotely or have deleted incorrect ones, push the new local tags:
```bash
# Push to GitHub
git push github refs/heads/v{MAJOR}.{MINOR}.{PATCH}:refs/heads/v{MAJOR}.{MINOR}.{PATCH}
git push github --tags
# Push to Gitea
git push gitea refs/heads/v{MAJOR}.{MINOR}.{PATCH}:refs/heads/v{MAJOR}.{MINOR}.{PATCH}
git push gitea --tags
```
### 8. Merge into Main Branch
Merge the version branch into the main branch:
```bash
git checkout main
git merge v{MAJOR}.{MINOR}.{PATCH} --no-ff -m "Merge v{MAJOR}.{MINOR}.{PATCH} into main"
git push github main
git push gitea main
```
## Version Numbering Guidelines
Follow semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Incompatible API changes
- **MINOR**: Add functionality in a backward-compatible manner
- **PATCH**: Backward-compatible bug fixes
Examples:
- Bug fix: 1.0.0 → 1.0.1
- New feature: 1.0.0 → 1.1.0
- Breaking change: 1.0.0 → 2.0.0
## GitHub Actions Workflow
When you push a tag, the GitHub Actions workflow will:
1. Build the plugin
2. Create a ZIP file
3. Create a GitHub release
4. Attach the ZIP file to the release
You can monitor the workflow in the "Actions" tab of the GitHub repository.
## WordPress.org Deployment (If Applicable)
If the plugin is hosted on WordPress.org:
1. Ensure the `readme.txt` file is properly formatted
2. Ensure the stable tag matches the new version
3. Use the WordPress.org SVN repository to deploy the new version
## Post-Release Tasks
After releasing a new version:
1. Update the wiki documentation:
- Update the Changelog.md file in the .wiki directory to match the main CHANGELOG.md
- Add the new version information to the Home.md file in the Latest Updates section
- Ensure all wiki pages are up-to-date with the new features or changes
- Verify that the _Sidebar.md file has the correct navigation structure
2. Verify that GitHub Actions workflows are running correctly:
- Check that the release workflow created the release with the correct assets
- Check that the sync-wiki workflow synced the wiki changes
- Fix any permissions issues in the workflow files if needed
3. Announce the release in relevant channels
4. Monitor for any issues or feedback
5. Start planning the next release

184
.agents/wiki-documentation.md Normal file
View File

@@ -0,0 +1,184 @@
# Wiki Documentation Guide for AI Assistants
This document provides guidelines for maintaining and updating the wiki documentation for the WordPress Plugin Starter Template.
## Wiki Structure
The wiki documentation is organized into the following sections:
1. **User Documentation**:
- Home
- Starter Prompt (must be listed before Installation Guide)
- Installation Guide
- Usage Instructions
- Frequently Asked Questions
- Troubleshooting
2. **Developer Documentation**:
- Architecture Overview
- Customization Guide
- Extending the Plugin
- Coding Standards
- Release Process
3. **AI Documentation**:
- AI Workflow Documentation
4. **Additional Resources**:
- Changelog
- Contributing
## Wiki Files Location
The wiki documentation is stored in the `.wiki/` directory in the repository. This allows:
1. Version control of wiki content alongside the code
2. Automated synchronization with the GitHub wiki using GitHub Actions
3. Easy contribution to documentation through pull requests
## Synchronization Process
When changes are pushed to the `.wiki/` directory in the `main` branch, the GitHub Actions workflow `.github/workflows/sync-wiki.yml` automatically synchronizes these changes with the GitHub wiki.
## Documentation Standards
### General Guidelines
- Use clear, concise language
- Follow Markdown formatting conventions
- Include code examples where appropriate
- Use screenshots or diagrams for complex concepts
- Keep documentation up-to-date with code changes
### Markdown Formatting
- Use `#` for main headings
- Use `##` for section headings
- Use `###` for subsection headings
- Use backticks for inline code: `code`
- Use triple backticks for code blocks:
```php
// Code example
function example() {
return true;
}
```
- Use bullet points for lists
- Use numbered lists for sequential steps
- Use blockquotes for important notes: > Note
### Code Examples
- Include complete, working code examples
- Use proper syntax highlighting
- Include comments to explain complex parts
- Follow WordPress coding standards in examples
## Updating Documentation
### When to Update
Documentation should be updated:
1. When adding new features
2. When changing existing functionality
3. When fixing bugs that affect user experience
4. When improving or clarifying existing documentation
### How to Update
1. Identify the relevant wiki file(s) in the `.wiki/` directory
2. Make the necessary changes
3. **Always ensure the Changelog.md in the wiki is updated to match the main CHANGELOG.md file**
4. **Always ensure the _Sidebar.md file has the correct navigation structure with Starter Prompt listed before Installation Guide**
5. Commit and push the changes to the `main` branch
6. The GitHub Actions workflow will automatically sync the changes with the GitHub wiki
### Creating New Pages
To create a new wiki page:
1. Create a new Markdown file in the `.wiki/` directory
2. Name the file according to the page title (e.g., `New-Feature.md`)
3. Add a link to the new page in the appropriate section of `Home.md`
4. Add a link to the new page in `_Sidebar.md`
## Repository-Specific Documentation
When working in a multi-repository workspace, it's critical to ensure that wiki documentation accurately reflects the features and functionality of the **current repository only**.
### Avoiding Cross-Repository Confusion
1. **Verify Features Before Documenting**:
- Always verify that a feature exists in the current repository before documenting it
- Use `codebase-retrieval` to search for feature implementations
- Check the actual code, not just comments or references
2. **Repository-Specific Content**:
- Document only features that exist in the current repository
- Don't assume features from other repositories are present in this one
- Be explicit about which repository the documentation applies to
3. **Feature Inspiration vs. Existing Features**:
- If documenting a feature inspired by another repository but not yet implemented, clearly mark it as a proposed feature
- Don't document features as if they exist when they're only planned or inspired by other repositories
4. **Cross-Repository References**:
- If referencing functionality from another repository, clearly indicate that it's external
- Use phrases like "unlike Repository X, this plugin does not include..."
For detailed guidelines on working in multi-repository workspaces, see **@.ai-workflows/multi-repo-workspace.md**.
## Best Practices
### Content Guidelines
- Use clear, concise language
- Include step-by-step instructions for complex tasks
- Use screenshots or diagrams to illustrate concepts
- Provide code examples for developers
- Keep the documentation organized and easy to navigate
### Formatting Guidelines
- Use consistent Markdown formatting
- Use headings to create a clear hierarchy
- Use lists for steps or related items
- Use tables for structured data
- Use code blocks for code examples
### Maintenance Guidelines
- Review documentation regularly for accuracy
- Update documentation when code changes
- Remove outdated information
- Add new documentation for new features
- Respond to user feedback about documentation
## User-Focused Documentation
When writing documentation for users:
1. Assume minimal technical knowledge
2. Provide clear, step-by-step instructions
3. Include screenshots for visual guidance
4. Explain technical terms when necessary
5. Focus on what users want to accomplish
## Developer-Focused Documentation
When writing documentation for developers:
1. Assume familiarity with WordPress development
2. Provide technical details and explanations
3. Include code examples and API references
4. Explain architectural decisions
5. Focus on how to extend or customize the plugin
## Responding to User Feedback
Improve documentation based on user feedback:
1. Monitor GitHub issues and WordPress.org support forums for common questions
2. Update the FAQ and troubleshooting sections based on user feedback
3. Add new examples or clarifications based on user questions