wp-fix-plugin-does-not-exist-notices/.ai-assistant.md

# AI Assistant Guide for WordPress Plugin Development

This guide helps AI assistants understand the project structure, workflows, and best practices for this repository.

## AI IDE Configuration

This repository includes configuration files for various AI-powered development tools:

- `.aiconfig` - General AI configuration (model preferences, ignore patterns)
- `.augmentignore` - Ignore patterns for Augment
- `.cursorignore` - Ignore patterns for Cursor
- `.v0ignore` - Ignore patterns for v0
- `.windsurfignore` - Ignore patterns for Windsurf
- `.clinerc` - Configuration for Cline
- `.rooignore` - Ignore patterns for Roo
- `.geminiignore` - Ignore patterns for Gemini Code Assist
- `.loveablerc` - Configuration for Loveable
- `.boltignore` - Ignore patterns for Bolt
- `.codyignore` - Ignore patterns for Cody
- `.continuerc` - Configuration for Continue

All these files respect `.gitignore` patterns and only include additional tool-specific patterns. The `!` prefix can be used in these files to include files that are excluded by `.gitignore`.

## Project Overview

- **Plugin Name**: Fix 'Plugin file does not exist' Notices
- **Repository**: https://github.com/wpallstars/wp-fix-plugin-does-not-exist-notices
- **Description**: Adds missing plugins to your plugins list with a "Remove Notice" action link, allowing you to safely clean up invalid plugin references.

This plugin helps users clean up references to deleted plugins that cause "Plugin file does not exist" errors in the WordPress admin. It adds missing plugins to the plugins list with a "Remove Notice" link to safely remove invalid plugin entries.

## Reference Plugins

The `reference-plugins/` directory contains plugins that can be used for reference or inspiration. When developing new features or improving existing ones, you should:

1. Examine these reference plugins for best practices in code structure, organization, and implementation
2. Look for patterns in how they handle similar functionality
3. Consider their approach to user interface design and user experience
4. Study their documentation style and thoroughness

These plugins are not part of the codebase and are ignored by Git, but they provide valuable examples of WordPress plugin development standards and techniques.

## Version Management

### Version Numbering Convention

We follow [Semantic Versioning](https://semver.org/):
- **MAJOR.MINOR.PATCH** (e.g., 1.6.0)
  - **MAJOR**: Breaking changes
  - **MINOR**: New features, non-breaking
  - **PATCH**: Bug fixes, non-breaking

### When to Increment Version Numbers

- **PATCH** (1.6.0 → 1.6.1):
  - Bug fixes
  - Small text changes
  - Minor improvements that don't add new features

- **MINOR** (1.6.0 → 1.7.0):
  - New features
  - Significant improvements to existing functionality
  - Deprecation of features (but not removal)

- **MAJOR** (1.6.0 → 2.0.0):
  - Breaking changes
  - Removal of features
  - Major architectural changes

### Version Update Checklist

When updating the version number, always update these files:
1. `wp-fix-plugin-does-not-exist-notices.php` (Plugin header and version parameter in Plugin class initialization)
2. `CHANGELOG.md` (Add new version section)
3. `readme.txt` (Stable tag and Changelog section)
4. `README.md` (Update Changelog section to match readme.txt)
5. Update any JavaScript files that contain version constants (e.g., `admin/js/version-fix.js`)
6. Update `languages/wp-fix-plugin-does-not-exist-notices.pot` (Project-Id-Version and POT-Creation-Date)

**IMPORTANT**: Always ensure README.md is kept in sync with readme.txt for consistency across platforms.

## Git Workflow

### Branch Naming Convention

- Feature branches: `feature/descriptive-name`
- Bug fix branches: `fix/issue-description`
- Release branches: `v{MAJOR}.{MINOR}.{PATCH}`

### Commit Message Guidelines

- 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"

### Pre-Release Checklist

Before creating a new release, verify the following:

- [ ] Determine the correct version increment (MAJOR, MINOR, or PATCH) based on the changes
- [ ] Ensure all changes are documented in CHANGELOG.md
- [ ] Verify all code changes are tested and working correctly
- [ ] Check that all files are properly formatted and follow WordPress coding standards
- [ ] Ensure Git Updater configuration is correct (if applicable)

### Release Process

1. Create a new branch for the version: `git checkout -b v{MAJOR}.{MINOR}.{PATCH}` or use an existing feature branch
2. Update version numbers in ALL required files:
   - `wp-fix-plugin-does-not-exist-notices.php` (Plugin header and version parameter in Plugin class initialization)
   - `readme.txt` (Stable tag and Changelog section)
   - `CHANGELOG.md` (Add new version section at the top)
   - Any JavaScript files with version constants (e.g., `admin/js/version-fix.js`)
   - `languages/wp-fix-plugin-does-not-exist-notices.pot` (Project-Id-Version)
3. Run the build script to create the plugin ZIP file and deploy to local testing environment:
   ```
   ./build.sh {MAJOR}.{MINOR}.{PATCH}
   ```
4. Test the plugin thoroughly in the local WordPress environment
5. Commit changes: `git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - Brief description of changes"`
6. Create a tag for the new version:
   ```
   git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Version {MAJOR}.{MINOR}.{PATCH} - Brief description of changes"
   ```
7. Push the branch and tag to all remotes:
   ```
   git push github feature/branch-name
   git push gitea feature/branch-name
   git push github v{MAJOR}.{MINOR}.{PATCH}
   git push gitea v{MAJOR}.{MINOR}.{PATCH}
   ```
8. Verify the GitHub release is created with the ZIP file attached
9. When ready to merge to main, create a pull request or merge directly:
   ```
   git checkout main
   git merge feature/branch-name --no-ff
   git push github main
   git push gitea main
   ```

## Build Process

The build process is handled by `build.sh`:
1. Creates build directory
2. Installs composer dependencies
3. Copies required files to build directory
4. Creates ZIP file
5. Automatically deploys to local WordPress testing environment

To build the plugin and deploy to local testing:
```
./build.sh {MAJOR}.{MINOR}.{PATCH}
```

This will create a ZIP file named `wp-fix-plugin-does-not-exist-notices-{MAJOR}.{MINOR}.{PATCH}.zip` and deploy the plugin to your local WordPress testing environment.

## Remote Repositories

The plugin is hosted on multiple repositories:
- GitHub: https://github.com/wpallstars/wp-fix-plugin-does-not-exist-notices
- Gitea: https://gitea.wpallstars.com/wpallstars/wp-fix-plugin-does-not-exist-notices
- WordPress.org: https://wordpress.org/plugins/wp-fix-plugin-does-not-exist-notices/

Always push changes to all remotes to keep them in sync.

## GitHub Actions

The repository uses GitHub Actions for automated builds and deployments:
- Triggered by tags matching the pattern `v*`
- Builds the plugin
- Creates a GitHub release
- Deploys to WordPress.org

## Testing Guidelines

Before releasing:
1. Test with the latest WordPress version
2. Test with PHP 7.0+ (minimum supported version)
3. Verify all features work as expected
4. Check for any PHP warnings or notices

### Local Testing Environment

Local environment variables and paths are documented in `.ai-workflows/local-env-vars.md`. This includes:

- Repository paths
- Local WordPress testing environment paths
- URLs for testing and development tools
- Build and deploy script locations

Refer to this file for the most up-to-date information about the local development environment.

### Using WP-CLI with LocalWP

WP-CLI can be used with LocalWP for various tasks:

```bash
# Navigate to the WordPress directory
cd ~/Local/plugin-testing/app/public

# Run WP-CLI commands
~/Local/plugin-testing/app/bin/wp plugin list
~/Local/plugin-testing/app/bin/wp transient delete --all
~/Local/plugin-testing/app/bin/wp cache flush
```

## Common Tasks for AI Assistants

### Creating a New Release

```
# 1. Start from a feature branch or create a new branch
git checkout feature/branch-name
# or
git checkout -b feature/new-feature-name

# 2. Update version numbers in ALL required files
# - wp-fix-plugin-does-not-exist-notices.php (header and class initialization)
# - CHANGELOG.md
# - readme.txt (Stable tag and Changelog section)
# - Any JavaScript files with version constants
# - languages/wp-fix-plugin-does-not-exist-notices.pot

# 3. Build and test locally
./build.sh 1.7.0
# Test in local WordPress environment

# 4. Commit changes
git add .
git commit -m "Version 1.7.0 - Brief description of changes"

# 5. Create a tag
git tag -a v1.7.0 -m "Version 1.7.0 - Brief description of changes"

# 6. Push branch and tag to remotes
git push github feature/branch-name
git push gitea feature/branch-name
git push github v1.7.0
git push gitea v1.7.0

# 7. Verify GitHub release is created with ZIP file
# Check: https://github.com/wpallstars/wp-fix-plugin-does-not-exist-notices/releases

# 8. Merge to main when ready
git checkout main
git merge feature/branch-name --no-ff
git push github main
git push gitea main
```

### Adding a New Feature

```
# 1. Create feature branch from main
git checkout main
git checkout -b feature/new-feature-name

# 2. Make changes and commit
git add .
git commit -m "Add new feature"

# 3. Test locally
# (Run tests, verify functionality)

# 4. When ready for release, merge to a version branch
git checkout -b v1.7.0
git merge feature/new-feature-name --no-ff

# 5. Continue with the release process
# (Update version numbers, etc.)
```

### Fixing a Bug

```
# 1. Create bugfix branch from main
git checkout main
git checkout -b fix/bug-description

# 2. Make changes and commit
git add .
git commit -m "Fix #123: Fix bug description"

# 3. Test locally
# (Run tests, verify functionality)

# 4. When ready for release, merge to a version branch
git checkout -b v1.6.5
git merge fix/bug-description --no-ff

# 5. Continue with the release process
# (Update version numbers, etc.)
```

### Testing a Previous Version

```
# Checkout a specific tag for testing
git checkout v1.6.3

# Or create a test branch from a specific tag
git checkout v1.6.3 -b test/some-feature
```