From 6b5267177f943debcb108ee00ff5fc4daf4875cc Mon Sep 17 00:00:00 2001
From: Marcus Quinn <6428977+marcusquinn@users.noreply.github.com>
Date: Sat, 12 Apr 2025 02:12:00 +0100
Subject: [PATCH] Update Git workflow documentation for better collaboration
 and testing

---
 .ai-assistant.md                            | 80 +++++++++++++++-----
 .github/ai-workflows/bug-fixing.md          | 43 ++++++++++-
 .github/ai-workflows/feature-development.md | 29 +++++++-
 .github/ai-workflows/release-process.md     | 81 +++++++++++++++++----
 4 files changed, 191 insertions(+), 42 deletions(-)

diff --git a/.ai-assistant.md b/.ai-assistant.md
index fdd9c7a..d92476e 100644
--- a/.ai-assistant.md
+++ b/.ai-assistant.md
@@ -79,23 +79,30 @@ Before creating a new release, verify the following:
    - `FPDEN_VERSION` constant in the main plugin file
    - `readme.txt` (Stable tag)
    - `README.md` (Ensure changelog is updated)
+   - `languages/fix-plugin-does-not-exist-notices.pot` (Project-Id-Version)
    - Any other files that reference the version number
 3. Update CHANGELOG.md with all changes
 4. Update readme.txt changelog section
 5. Update README.md changelog section to match readme.txt
 6. Commit changes: `git commit -m "Prepare release v{MAJOR}.{MINOR}.{PATCH}"`
-7. Push branch to all remotes:
+7. Test changes locally on the version branch
+8. When satisfied with testing, merge to main:
    ```
-   git push github HEAD:v{MAJOR}.{MINOR}.{PATCH}
-   git push gitea HEAD:v{MAJOR}.{MINOR}.{PATCH}
+   git checkout main
+   git merge v{MAJOR}.{MINOR}.{PATCH} --no-ff
    ```
-8. Create and push a tag to trigger the GitHub Actions workflow:
+9. Push main to all remotes:
    ```
-   git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Release version {MAJOR}.{MINOR}.{PATCH}"
-   git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH}
-   git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH}
+   git push github main
+   git push gitea main
    ```
-9. Verify the GitHub Actions workflow completes successfully
+10. Create and push a tag to trigger the GitHub Actions workflow:
+    ```
+    git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Release version {MAJOR}.{MINOR}.{PATCH}"
+    git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH}
+    git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH}
+    ```
+11. Verify the GitHub Actions workflow completes successfully
 
 ## Build Process
 
@@ -141,6 +148,7 @@ Before releasing:
 
 ```
 # 1. Create a new branch
+git checkout main
 git checkout -b v1.7.0
 
 # 2. Update version numbers in ALL required files
@@ -148,17 +156,25 @@ git checkout -b v1.7.0
 # - CHANGELOG.md
 # - readme.txt
 # - README.md
+# - languages/fix-plugin-does-not-exist-notices.pot
 # - FPDEN_VERSION constant
 
 # 3. Commit changes
 git add .
 git commit -m "Prepare release v1.7.0"
 
-# 4. Push to remotes
-git push github HEAD:v1.7.0
-git push gitea HEAD:v1.7.0
+# 4. Test changes locally on the version branch
+# (Run tests, verify functionality)
 
-# 5. Create and push tag
+# 5. Merge to main when ready
+git checkout main
+git merge v1.7.0 --no-ff
+
+# 6. Push main to remotes
+git push github main
+git push gitea main
+
+# 7. Create and push tag
 git tag -a v1.7.0 -m "Release version 1.7.0"
 git push github refs/tags/v1.7.0
 git push gitea refs/tags/v1.7.0
@@ -167,29 +183,53 @@ git push gitea refs/tags/v1.7.0
 ### Adding a New Feature
 
 ```
-# 1. Create feature branch
+# 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. Push to remotes
-git push github HEAD:feature/new-feature-name
-git push gitea HEAD:feature/new-feature-name
+# 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
+# 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. Push to remotes
-git push github HEAD:fix/bug-description
-git push gitea HEAD: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
 ```
diff --git a/.github/ai-workflows/bug-fixing.md b/.github/ai-workflows/bug-fixing.md
index 3c5a7be..7b706b0 100644
--- a/.github/ai-workflows/bug-fixing.md
+++ b/.github/ai-workflows/bug-fixing.md
@@ -64,27 +64,60 @@ git commit -m "Fix #123: Brief description of the bug fix"
 
 If there's an issue number, reference it in the commit message.
 
-### 7. Push to Remote
+### 7. Prepare for Release
 
-Push the bug fix branch to the remote repositories:
+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
 ```
 
-### 8. Create Pull Request (Optional)
+### 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 main branch.
+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, determine the appropriate version increment:
 
 - **PATCH** (e.g., 1.6.0 → 1.6.1): For most bug fixes that don't change functionality
+  - **IMPORTANT**: Always increment the patch version for every change, even small ones, to make rollbacks easier if issues are found in testing
 - **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
 
+## 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:
@@ -108,6 +141,8 @@ Increment the PATCH version and update all version numbers:
 - FPDEN_VERSION constant
 - CHANGELOG.md
 - readme.txt
+- README.md
+- languages/fix-plugin-does-not-exist-notices.pot (Project-Id-Version)
 
 ### 4. Commit and Push
 
diff --git a/.github/ai-workflows/feature-development.md b/.github/ai-workflows/feature-development.md
index 8c7dc2a..7730c13 100644
--- a/.github/ai-workflows/feature-development.md
+++ b/.github/ai-workflows/feature-development.md
@@ -33,6 +33,7 @@ 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 inline documentation/comments
+- Remember that any feature addition will require a version increment in all relevant files
 
 ### 4. Testing
 
@@ -52,18 +53,38 @@ git add .
 git commit -m "Add feature: descriptive name"
 ```
 
-### 6. Push to Remote
+### 6. Prepare for Release
 
-Push the feature branch to the remote repositories:
+When the feature is ready to be released:
+
+1. Create a version branch for the release:
+
+```bash
+git checkout -b v{MAJOR}.{MINOR}.{PATCH}
+```
+
+2. Merge your feature branch into the version branch:
+
+```bash
+git merge feature/descriptive-name --no-ff
+```
+
+3. Update version numbers and changelog entries
+
+4. Follow the standard release process from this point
+
+### 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
 ```
 
-### 7. Create Pull Request (Optional)
+### 8. Create Pull Request (Optional)
 
-If the repository uses pull requests for code review, create a pull request from the feature branch to the main branch.
+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
 
diff --git a/.github/ai-workflows/release-process.md b/.github/ai-workflows/release-process.md
index b91264c..b74ff1a 100644
--- a/.github/ai-workflows/release-process.md
+++ b/.github/ai-workflows/release-process.md
@@ -15,6 +15,7 @@ This document provides step-by-step instructions for AI assistants to help with
 Based on the changes made, determine the appropriate version increment:
 
 1. **PATCH** (e.g., 1.6.0 → 1.6.1): For bug fixes and minor improvements
+   - **IMPORTANT**: Always increment the patch version for every change, even small ones, to make rollbacks easier if issues are found in testing
 2. **MINOR** (e.g., 1.6.0 → 1.7.0): For new features and significant improvements
 3. **MAJOR** (e.g., 1.6.0 → 2.0.0): For breaking changes
 
@@ -72,7 +73,16 @@ Add a new section at the top of the CHANGELOG.md file:
 - Bug fix 2
 ```
 
-#### c. readme.txt
+#### c. POT File (languages/fix-plugin-does-not-exist-notices.pot)
+
+Update the Project-Id-Version and POT-Creation-Date:
+
+```
+"Project-Id-Version: Fix 'Plugin file does not exist.' Notices {MAJOR}.{MINOR}.{PATCH}\n"
+"POT-Creation-Date: YYYY-MM-DDT00:00:00+00:00\n"
+```
+
+#### d. readme.txt
 
 Update the stable tag:
 
@@ -102,18 +112,38 @@ Brief description of the most important changes in this release
 ### 3. Commit Changes
 
 ```bash
-git add fix-plugin-does-not-exist-notices.php CHANGELOG.md readme.txt
+git add fix-plugin-does-not-exist-notices.php CHANGELOG.md readme.txt README.md languages/fix-plugin-does-not-exist-notices.pot
 git commit -m "Prepare release v{MAJOR}.{MINOR}.{PATCH}"
 ```
 
-### 4. Push Branch to Remotes
+### 4. Test Changes Locally
+
+Test the changes thoroughly on the version branch to ensure everything works as expected:
+
+- Test with the latest WordPress version
+- Test with PHP 7.0+ (minimum supported version)
+- Verify all features work as expected
+- Check for any PHP warnings or notices
+
+### 5. Merge to Main
+
+When satisfied with testing, merge the version branch to main:
 
 ```bash
-git push github HEAD:v{MAJOR}.{MINOR}.{PATCH}
-git push gitea HEAD:v{MAJOR}.{MINOR}.{PATCH}
+git checkout main
+git merge v{MAJOR}.{MINOR}.{PATCH} --no-ff
 ```
 
-### 5. Create and Push Tag
+The `--no-ff` flag creates a merge commit even if a fast-forward merge is possible, which helps preserve the branch history.
+
+### 6. Push Main to Remotes
+
+```bash
+git push github main
+git push gitea main
+```
+
+### 7. Create and Push Tag
 
 ```bash
 git tag -a v{MAJOR}.{MINOR}.{PATCH} -m "Release version {MAJOR}.{MINOR}.{PATCH}"
@@ -121,17 +151,29 @@ git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH}
 git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH}
 ```
 
-### 6. Monitor GitHub Actions
+### 8. Monitor GitHub Actions
 
 Open the GitHub Actions page to monitor the build and deployment process:
 https://github.com/wpallstars/fix-plugin-does-not-exist-notices/actions
 
-### 7. Verify Release
+### 9. Verify Release
 
 - [ ] Check that the GitHub release was created successfully
 - [ ] Verify that the plugin was deployed to WordPress.org
 - [ ] Test the plugin from WordPress.org to ensure it works correctly
 
+## 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
+```
+
 ## Rollback Procedure (If Needed)
 
 If issues are discovered after release:
@@ -151,16 +193,27 @@ Make the necessary changes to fix the issues.
 
 Increment the PATCH version and update all version numbers as described above.
 
-### 4. Commit and Push
+### 4. Test the Hotfix
+
+Test the hotfix thoroughly to ensure it resolves the issue without introducing new problems.
+
+### 5. Commit Changes
 
 ```bash
 git add .
 git commit -m "Fix issues in v{MAJOR}.{MINOR}.{PATCH}"
-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
+### 6. Merge to Main
+
+```bash
+git checkout main
+git merge hotfix/v{MAJOR}.{MINOR}.{PATCH+1} --no-ff
+git push github main
+git push gitea main
+```
+
+### 7. Create and Push Tag
 
 ```bash
 git tag -a v{MAJOR}.{MINOR}.{PATCH+1} -m "Hotfix release version {MAJOR}.{MINOR}.{PATCH+1}"
@@ -168,6 +221,6 @@ git push github refs/tags/v{MAJOR}.{MINOR}.{PATCH+1}
 git push gitea refs/tags/v{MAJOR}.{MINOR}.{PATCH+1}
 ```
 
-### 6. Monitor and Verify
+### 8. Monitor and Verify
 
-Follow steps 6 and 7 from the release process to monitor and verify the hotfix release.
+Follow steps 8 and 9 from the release process to monitor and verify the hotfix release.