From 9afa732c2030147978d44833724b000a8c76b0c9 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Thu, 17 Apr 2025 04:12:01 +0100 Subject: [PATCH] Update AI assistant documentation for wiki management --- .ai-assistant.md | 16 ++++ .ai-workflows/feature-development.md | 8 ++ .ai-workflows/readme.md | 1 + .ai-workflows/release-process.md | 37 +++++++- .ai-workflows/wiki-documentation.md | 127 +++++++++++++++++++++++++++ 5 files changed, 186 insertions(+), 3 deletions(-) create mode 100644 .ai-workflows/wiki-documentation.md diff --git a/.ai-assistant.md b/.ai-assistant.md index 9825dbb..9f3745d 100644 --- a/.ai-assistant.md +++ b/.ai-assistant.md @@ -23,6 +23,7 @@ Detailed workflow documentation is available in the `.ai-workflows/` directory: - **@.ai-workflows/incremental-development.md**: Time-efficient approach for incremental development and testing - **@.ai-workflows/local-env-vars.md**: Local development environment paths and URLs - **@.ai-workflows/release-process.md**: Steps for preparing and publishing releases +- **@.ai-workflows/wiki-documentation.md**: Guidelines for maintaining wiki documentation ## Version Management @@ -108,6 +109,21 @@ AI assistants should maintain a record of developer preferences in **@.ai-workfl This ensures consistency across coding sessions and reduces the need for developers to repeatedly explain their preferences. +## Wiki Documentation + +The plugin has a GitHub wiki that is automatically synced from the `.wiki` directory in the repository. When making changes to the codebase, it's important to keep the wiki documentation up-to-date. + +### Key Principles + +- **Documentation Synchronization**: Ensure that README.md, readme.txt, and wiki documentation are kept in sync +- **Feature Documentation**: Document new features, hooks, and filters in all relevant places +- **Code Structure Documentation**: Update technical documentation when changing code structure +- **Automatic Syncing**: Changes to the `.wiki` directory are automatically synced to the GitHub wiki + +For detailed guidelines on maintaining wiki documentation, see **@.ai-workflows/wiki-documentation.md**. + +**IMPORTANT**: When updating features, functions, hooks, or code structure, always check if the wiki documentation needs to be updated as well. This ensures that users have access to accurate and up-to-date information. + ## Common Tasks For detailed instructions on common tasks like creating releases, adding features, fixing bugs, and testing previous versions, see **@.ai-workflows/release-process.md**. diff --git a/.ai-workflows/feature-development.md b/.ai-workflows/feature-development.md index de852b6..8c09b2c 100644 --- a/.ai-workflows/feature-development.md +++ b/.ai-workflows/feature-development.md @@ -35,9 +35,17 @@ 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: diff --git a/.ai-workflows/readme.md b/.ai-workflows/readme.md index 6af66b6..47774c0 100644 --- a/.ai-workflows/readme.md +++ b/.ai-workflows/readme.md @@ -13,5 +13,6 @@ This directory contains workflow documentation for AI assistants working with th - **incremental-development.md**: Time-efficient approach for incremental development and testing - **local-env-vars.md**: Local development environment paths and URLs - **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. diff --git a/.ai-workflows/release-process.md b/.ai-workflows/release-process.md index 04288b3..5c6a000 100644 --- a/.ai-workflows/release-process.md +++ b/.ai-workflows/release-process.md @@ -8,6 +8,8 @@ This document provides step-by-step instructions for AI assistants to help with - [ ] All bug fixes for this release are complete - [ ] CHANGELOG.md is up to date - [ ] readme.txt is up to date +- [ ] README.md is up to date +- [ ] Wiki documentation in the `.wiki` directory is up to date - [ ] All tests pass ## Determining the New Version Number @@ -127,7 +129,7 @@ Update the Changelog section in the main README.md file to match the changes in ### {PREVIOUS_VERSION} ``` -**IMPORTANT**: Always keep the changelogs in README.md, readme.txt, and CHANGELOG.md in sync to avoid confusion. +**IMPORTANT**: Always keep the changelogs in README.md, readme.txt, CHANGELOG.md, and .wiki/Changelog.md in sync to avoid confusion. #### e. POT File (languages/wp-fix-plugin-does-not-exist-notices.pot) @@ -157,6 +159,31 @@ Add a new entry to the changelog section: * Change 3 ``` +#### g. Wiki Documentation (.wiki/Changelog.md) + +Update the Changelog.md file in the .wiki directory to match the changes in CHANGELOG.md: + +```markdown +# Changelog + +This page documents all notable changes to the "Fix 'Plugin file does not exist' Notices" plugin. + +## Version {MAJOR}.{MINOR}.{PATCH} (YYYY-MM-DD) +- Change 1 +- Change 2 +- Change 3 + +## Version {PREVIOUS_VERSION} (YYYY-MM-DD) +``` + +Also update any other wiki pages that might be affected by the changes in this release, such as: +- .wiki/Home.md (if major features were added) +- .wiki/How-It-Works.md (if the internal workings changed) +- .wiki/Frequently-Asked-Questions.md (if new FAQs were added) +- Feature-specific pages (if features were added or modified) + +For detailed guidelines on maintaining wiki documentation, see **@.ai-workflows/wiki-documentation.md**. + ### 3. Build and Test #### Local Testing (Default for Incremental Development) @@ -194,10 +221,12 @@ This is necessary when testing Git Updater integration or other features that re ### 4. Commit Changes ```bash -git add wp-fix-plugin-does-not-exist-notices.php CHANGELOG.md README.md readme.txt languages/wp-fix-plugin-does-not-exist-notices.pot +git add wp-fix-plugin-does-not-exist-notices.php CHANGELOG.md README.md readme.txt languages/wp-fix-plugin-does-not-exist-notices.pot .wiki/Changelog.md git commit -m "Version {MAJOR}.{MINOR}.{PATCH} - Brief description of changes" ``` +Note: If you've updated other wiki pages, make sure to include them in the git add command as well. + Note: Make sure to include README.md in your commit to keep all changelog files in sync. ### 5. Create a Tag @@ -260,7 +289,9 @@ The `--no-ff` flag creates a merge commit even if a fast-forward merge is possib - [ ] Verify that the plugin was deployed to WordPress.org (if applicable) - [ ] Test the plugin from the GitHub release ZIP to ensure it works correctly - [ ] Verify that Git Updater can detect and install the new version -- [ ] Confirm that all changelog files (README.md, readme.txt, and CHANGELOG.md) are in sync +- [ ] Confirm that all changelog files (README.md, readme.txt, CHANGELOG.md, and .wiki/Changelog.md) are in sync +- [ ] Verify that all wiki documentation is up to date and accurately reflects the changes in this release +- [ ] Check that the wiki sync GitHub Action has run successfully (if changes were made to the .wiki directory) - [ ] Verify that all CI/CD checks have passed for the release ## Testing Previous Versions diff --git a/.ai-workflows/wiki-documentation.md b/.ai-workflows/wiki-documentation.md new file mode 100644 index 0000000..7c8be40 --- /dev/null +++ b/.ai-workflows/wiki-documentation.md @@ -0,0 +1,127 @@ +# Wiki Documentation Management + +This document outlines the process for maintaining and updating the wiki documentation for the "Fix 'Plugin file does not exist' Notices" plugin. + +## Wiki Structure + +The wiki documentation is stored in the `.wiki` directory in the repository. This directory contains Markdown files that are automatically synced to the GitHub wiki when changes are pushed to the main branch. + +### Key Files + +- **Home.md**: The landing page of the wiki +- **_Sidebar.md**: The sidebar navigation for the wiki +- **README.md**: Instructions for contributing to the wiki +- **Other .md files**: Individual documentation pages +- **assets/**: Directory for images and other assets used in the documentation + +## Documentation Synchronization + +To ensure consistency across all documentation sources, follow these guidelines: + +### When Updating README.md or readme.txt + +1. Identify the sections that need to be reflected in the wiki documentation +2. Update the corresponding wiki pages in the `.wiki` directory +3. Ensure that feature descriptions, usage instructions, and other relevant information are consistent across all documentation sources +4. Update the changelog in all locations: + - README.md + - readme.txt + - CHANGELOG.md + - .wiki/Changelog.md + +### When Adding New Features or Functions + +1. Document the feature in the appropriate README.md and readme.txt sections +2. Create or update the corresponding wiki page in the `.wiki` directory +3. Include: + - Feature description + - Usage instructions + - Examples + - Screenshots (if applicable) + - Any relevant configuration options + +### When Adding Hooks or Filters + +1. Document the hook or filter in the README.md file +2. Update or create the `.wiki/Hooks-and-Filters.md` page with: + - Hook/filter name + - Description + - Parameters + - Return value + - Example usage + - Default behavior + +### When Updating Code Structure + +1. Update the `.wiki/How-It-Works.md` page to reflect the new code structure +2. If the changes affect the plugin's architecture, update any relevant diagrams or explanations +3. Ensure that the documentation accurately reflects the current state of the codebase + +## Wiki Maintenance Workflow + +### Regular Maintenance + +1. Review the wiki documentation monthly to ensure it's up-to-date +2. Check for broken links, outdated information, or missing content +3. Update screenshots and examples to reflect the latest version of the plugin + +### Release-Driven Updates + +1. Before each release, review and update all wiki documentation +2. After the release, update the `.wiki/Changelog.md` file with the latest changes +3. Ensure that new features or changes are properly documented in the wiki + +### User-Driven Updates + +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 + +## 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 descriptive file names with hyphens instead of spaces +- Include a title at the top of each page using a level 1 heading (`# Title`) +- Use appropriate heading levels (H2, H3, etc.) for section organization +- Include links to related pages where appropriate + +### Workflow Integration + +- When working on code changes, consider documentation updates as part of the same task +- Create or update wiki documentation in the same branch as code changes +- Include documentation updates in pull request descriptions +- Request documentation review as part of the code review process + +## Automatic Syncing + +When changes are pushed to the main branch and include modifications to files in the `.wiki` directory, a GitHub Action will automatically sync these changes to the GitHub wiki. This ensures that the documentation is always up-to-date with the latest changes. + +The sync workflow is defined in `.github/workflows/sync-wiki.yml` and runs whenever changes to the `.wiki` directory are pushed to the main branch. + +## Documentation Testing + +Before pushing documentation changes: + +1. Preview the Markdown files locally to ensure proper formatting +2. Check all links to ensure they work correctly +3. Verify that code examples are correct and up-to-date +4. Ensure that screenshots accurately reflect the current UI + +## Troubleshooting Wiki Sync Issues + +If the wiki sync fails: + +1. Check the GitHub Actions logs for error messages +2. Verify that the wiki repository exists and is accessible +3. Ensure that the GitHub token has the necessary permissions +4. Try manually syncing the wiki by following the steps in the workflow file