diff --git a/.ai-assistant.md b/.ai-assistant.md index cadbf22..c38dbcd 100644 --- a/.ai-assistant.md +++ b/.ai-assistant.md @@ -16,7 +16,7 @@ This workspace may contain multiple repository folders. Always focus ONLY on the - **Plugin Slug**: wp-plugin-starter-template - **Text Domain**: wp-plugin-starter-template - **Namespace**: WPALLSTARS\PluginStarterTemplate -- **Version**: 0.1.0 +- **Version**: 0.1.1 - **Requires WordPress**: 5.0+ - **Requires PHP**: 7.0+ - **License**: GPL-2.0+ diff --git a/.ai-workflows/folder-structure.md b/.ai-workflows/folder-structure.md new file mode 100644 index 0000000..e63e665 --- /dev/null +++ b/.ai-workflows/folder-structure.md @@ -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 diff --git a/.ai-workflows/incremental-development.md b/.ai-workflows/incremental-development.md new file mode 100644 index 0000000..3aaed46 --- /dev/null +++ b/.ai-workflows/incremental-development.md @@ -0,0 +1,225 @@ +# 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. diff --git a/STARTER-PROMPT.md b/STARTER-PROMPT.md new file mode 100644 index 0000000..f2bc4c8 --- /dev/null +++ b/STARTER-PROMPT.md @@ -0,0 +1,175 @@ +# WordPress Plugin Starter Template - AI Assistant Prompt + +This document provides a comprehensive prompt to help you get started with creating your own WordPress plugin using this starter template with the assistance of AI tools like GitHub Copilot, Claude, or ChatGPT. + +## Initial Setup Prompt + +Use the following prompt to guide the AI assistant in helping you set up your new plugin based on this template: + +``` +I'm creating a new WordPress plugin based on the wp-plugin-starter-template-for-ai-coding template. Please help me customize this template for my specific plugin needs. + +Here are the details for my new plugin: + +- Plugin Name: [YOUR PLUGIN NAME] +- Plugin Slug: [YOUR-PLUGIN-SLUG] +- Text Domain: [your-plugin-text-domain] +- Namespace: [VENDOR]\[PluginName] +- Description: [BRIEF DESCRIPTION OF YOUR PLUGIN] +- Version: 0.1.0 (starting version) +- Author: [YOUR NAME/ORGANIZATION] +- Author URI: [YOUR WEBSITE] +- License: GPL-2.0+ (or specify another compatible license) +- Requires WordPress: [MINIMUM WP VERSION, e.g., 5.0] +- Requires PHP: [MINIMUM PHP VERSION, e.g., 7.0] +- GitHub Repository: [YOUR GITHUB REPO URL] +- Gitea Repository (if applicable): [YOUR GITEA REPO URL] + +I need help with the following tasks: + +1. Updating all template placeholders with my plugin information +2. Customizing the plugin structure for my specific needs +3. Setting up the initial functionality for my plugin + +Please guide me through this process step by step, starting with identifying all files that need to be updated with my plugin information. +``` + +## Files That Need Updating + +The AI will help you identify and update the following files with your plugin information: + +1. **Main Plugin File**: Rename `wp-plugin-starter-template.php` to `your-plugin-slug.php` and update all plugin header information +2. **README.md**: Update with your plugin details, features, and installation instructions +3. **readme.txt**: Update WordPress.org plugin repository information +4. **CHANGELOG.md**: Initialize with your starting version +5. **composer.json**: Update package name and description +6. **languages/pot file**: Rename and update the POT file +7. **.github/workflows/**: Update GitHub Actions workflows with your repository information +8. **.wiki/**: Update wiki documentation with your plugin information +9. **.ai-assistant.md**: Update AI assistant guidance for your specific plugin +10. **includes/plugin.php**: Update namespace and class references +11. **includes/core.php**: Update namespace and customize core functionality +12. **admin/lib/admin.php**: Update namespace and customize admin functionality + +## Customization Process + +After providing the initial information, follow this process with your AI assistant: + +### 1. File Renaming + +Ask the AI to help you identify all files that need to be renamed: + +``` +Please list all files that need to be renamed to match my plugin slug, and provide the commands to rename them. +``` + +### 2. Namespace Updates + +Ask the AI to help you update all namespace references: + +``` +Please help me update all namespace references from WPALLSTARS\PluginStarterTemplate to [VENDOR]\[PluginName] throughout the codebase. +``` + +### 3. Text Domain Updates + +Ask the AI to help you update all text domain references: + +``` +Please help me update all text domain references from 'wp-plugin-starter-template' to '[your-plugin-text-domain]' throughout the codebase. +``` + +### 4. Function Prefix Updates + +Ask the AI to help you update any function prefixes: + +``` +Please help me update any function prefixes from 'wpst_' to '[your_prefix]_' throughout the codebase. +``` + +### 5. Customizing Core Functionality + +Ask the AI to help you customize the core functionality for your specific plugin needs: + +``` +Now I'd like to customize the core functionality for my plugin. Here's what my plugin should do: + +[DESCRIBE YOUR PLUGIN'S CORE FUNCTIONALITY] + +Please help me modify the includes/core.php file to implement this functionality. +``` + +### 6. Customizing Admin Interface + +Ask the AI to help you customize the admin interface for your specific plugin needs: + +``` +I'd like to customize the admin interface for my plugin. Here's what I need in the admin area: + +[DESCRIBE YOUR PLUGIN'S ADMIN INTERFACE NEEDS] + +Please help me modify the admin/lib/admin.php file and any other necessary files to implement this. +``` + +### 7. Testing Setup + +Ask the AI to help you set up testing for your plugin: + +``` +Please help me update the testing setup to match my plugin's namespace and functionality. I want to ensure I have proper test coverage for the core features. +``` + +## Additional Customization Areas + +Depending on your plugin's needs, you might want to ask the AI for help with: + +1. **Custom Post Types**: Setting up custom post types and taxonomies +2. **Settings API**: Implementing WordPress Settings API for your plugin options +3. **Shortcodes**: Creating shortcodes for front-end functionality +4. **Widgets**: Developing WordPress widgets +5. **REST API**: Adding custom REST API endpoints +6. **Blocks**: Creating Gutenberg blocks +7. **Internationalization**: Ensuring proper i18n setup +8. **Database Tables**: Creating custom database tables if needed +9. **Cron Jobs**: Setting up WordPress cron jobs +10. **User Roles and Capabilities**: Managing custom user roles and capabilities + +## Final Review + +Once you've completed the customization, ask the AI to help you review everything: + +``` +Please help me review all the changes we've made to ensure: + +1. All template placeholders have been replaced with my plugin information +2. All namespaces, text domains, and function prefixes have been updated consistently +3. The plugin structure matches my specific needs +4. The initial functionality is properly implemented +5. All documentation (README.md, readme.txt, wiki) is updated and consistent + +Are there any issues or inconsistencies that need to be addressed? +``` + +## Building and Testing + +Finally, ask the AI to guide you through building and testing your plugin: + +``` +Please guide me through the process of building and testing my plugin: + +1. How do I use the build script to create a deployable version? +2. What tests should I run to ensure everything is working correctly? +3. How do I set up a local testing environment? +4. What should I check before releasing the first version? +``` + +## Remember + +- This template is designed to be a starting point. Feel free to add, remove, or modify components as needed for your specific plugin. +- The AI assistant can help you understand the existing code and make appropriate modifications, but you should review all changes to ensure they meet your requirements. +- Always test your plugin thoroughly before releasing it. +- Keep documentation updated as you develop your plugin. + +## Credits + +This plugin is based on the [WordPress Plugin Starter Template for AI Coding](https://github.com/wpallstars/wp-plugin-starter-template-for-ai-coding) by WPALLSTARS.