docs: add comprehensive guide for git history rewrite issues and solutions (refs #68)

Author: fxstein

docs/GIT_HISTORY_REWRITE_ISSUES.md

@@ -0,0 +1,233 @@
+# Git History Rewrite Issues and Solutions
+
+## Overview
+
+This document records issues encountered when using `git filter-repo` to rewrite git history and the solutions implemented to resolve them. This is particularly important for projects that use GitHub Actions for automated releases.
+
+## Issue: GitHub Actions Using Old History After Git Filter-Repo
+
+### Symptoms
+
+1. **Local vs. GitHub Actions Discrepancy**: 
+   - Local repository shows correct commit count (e.g., 137 commits since v00.52.00)
+   - GitHub Actions shows incorrect commit count (e.g., 398 commits since v00.52.00)
+
+2. **Release Notes Generation Problems**:
+   - Release notes include all issues from entire repository history
+   - Issues from much earlier versions appear in recent release notes
+   - Release notes are excessively long with hundreds of commits
+
+3. **Tag Hash Mismatches**:
+   - Local tag hash: `a0e7ead4ea13e3353eb8086faedbad596968ae1c`
+   - GitHub Actions tag hash: `3c45f4ef25d4fc36b4ba8d5ffaa889b03c268192`
+
+### Root Cause
+
+When `git filter-repo` rewrites git history:
+
+1. **New Commit Hashes**: All commit hashes change due to the rewrite
+2. **Tag References**: Tags still point to old commit hashes that no longer exist in the rewritten history
+3. **GitHub Caching**: GitHub may serve different versions of the repository to different clients
+4. **Incomplete Push**: The rewritten history and updated tags weren't fully pushed to GitHub
+
+### Detection Methods
+
+#### 1. Debug Output in Workflow
+
+Add debug steps to GitHub Actions workflow to detect the issue:
+
+```yaml
+- name: Verify Git History
+  run: |
+    echo "=== GIT HISTORY VERIFICATION ==="
+    echo "Checking if we have the correct rewritten history..."
+    
+    # Check if filter-repo evidence exists
+    if [[ -d ".git/filter-repo" ]]; then
+      echo "✅ Filter-repo evidence found - using rewritten history"
+    else
+      echo "❌ No filter-repo evidence found - may be using old history"
+    fi
+    
+    # Show commit range analysis
+    echo ""
+    echo "=== COMMIT RANGE ANALYSIS ==="
+    echo "Total commits since v${{ inputs.prev_version }}:"
+    git log --oneline v${{ inputs.prev_version }}..HEAD | wc -l
+    echo ""
+    echo "Unique issues referenced:"
+    git log --oneline v${{ inputs.prev_version }}..HEAD | grep -o "(refs #[0-9]*)" | sort | uniq | wc -l
+```
+
+#### 2. Tag Hash Verification
+
+Compare local and remote tag hashes:
+
+```bash
+# Local
+git rev-parse v00.52.00
+
+# Check what GitHub Actions sees
+gh run view <run-id> --log | grep "Tag v00.52.00:"
+```
+
+#### 3. Commit Count Comparison
+
+Compare expected vs. actual commit counts:
+
+```bash
+# Expected (local)
+git log --oneline v00.52.00..HEAD | wc -l
+
+# Actual (workflow output)
+# Check workflow logs for commit count
+```
+
+### Solutions
+
+#### 1. Force Push Tags (Primary Solution)
+
+After `git filter-repo`, force push all tags to update them on GitHub:
+
+```bash
+# Force push all tags with rewritten history
+git push --force --tags
+
+# Verify tag updates
+git push --force-with-lease --tags
+```
+
+#### 2. Workflow Detection and Prevention
+
+Add steps to GitHub Actions workflow to detect and prevent using old history:
+
+```yaml
+- name: Force Rewritten History
+  run: |
+    echo "=== FORCING REWRITTEN HISTORY ==="
+    
+    # Force fetch all refs to ensure we have the latest history
+    git fetch --all --tags --force
+    
+    # Verify we have the correct history
+    echo "Current HEAD: $(git rev-parse HEAD)"
+    echo "Tag v${{ inputs.prev_version }}: $(git rev-parse v${{ inputs.prev_version }})"
+    
+    # Check if we're using the rewritten history
+    if git log --oneline v${{ inputs.prev_version }}..HEAD | wc -l | grep -q "397"; then
+      echo "❌ Still using old history (397 commits detected)"
+      echo "Attempting to force rewritten history..."
+      
+      # Try to fetch the rewritten history explicitly
+      git fetch origin --force
+      git reset --hard origin/main
+      git fetch --all --tags --force
+      
+      # Verify again
+      COMMIT_COUNT=$(git log --oneline v${{ inputs.prev_version }}..HEAD | wc -l)
+      echo "Commit count after force fetch: $COMMIT_COUNT"
+      
+      if [[ $COMMIT_COUNT -gt 200 ]]; then
+        echo "❌ Still using old history. Manual intervention required."
+        echo "The repository may need to be re-pushed with the rewritten history."
+        exit 1
+      else
+        echo "✅ Now using rewritten history"
+      fi
+    else
+      echo "✅ Using rewritten history"
+    fi
+```
+
+#### 3. Improved Script Error Handling
+
+Update release note generation scripts to fail on incorrect commit ranges:
+
+```zsh
+# In generate-release-notes.zsh
+if ! git rev-parse "v${previous_version}" &>/dev/null; then
+    print_error "Previous version tag v${previous_version} not found"
+    print_error "Available tags:"
+    git tag --list "v*" | head -10
+    exit 1
+fi
+
+# Verify commit range is reasonable
+local commit_count=$(git log --oneline "v${previous_version}..HEAD" | wc -l)
+if [[ $commit_count -gt 200 ]]; then
+    print_warning "Large commit count detected: $commit_count"
+    print_warning "This may indicate git history issues"
+    print_warning "Expected: ~100-150 commits for recent releases"
+fi
+```
+
+### Prevention Strategies
+
+#### 1. Pre-Workflow Verification
+
+Before running workflows, verify local and remote are in sync:
+
+```bash
+# Check tag consistency
+git ls-remote --tags origin | grep v00.52.00
+git rev-parse v00.52.00
+
+# Check commit count consistency
+git log --oneline v00.52.00..HEAD | wc -l
+```
+
+#### 2. Workflow Validation
+
+Add validation steps to workflows to catch issues early:
+
+```yaml
+- name: Validate Git History
+  run: |
+    # Check for reasonable commit counts
+    COMMIT_COUNT=$(git log --oneline v${{ inputs.prev_version }}..HEAD | wc -l)
+    if [[ $COMMIT_COUNT -gt 200 ]]; then
+      echo "❌ Unreasonable commit count: $COMMIT_COUNT"
+      echo "This may indicate git history issues"
+      exit 1
+    fi
+```
+
+#### 3. Documentation Requirements
+
+- Document all git history rewrites
+- Record expected commit counts for each version range
+- Maintain a log of tag hash changes
+
+### Related Issues
+
+#### 1. Release Notes Generation
+
+- **Problem**: Scripts fall back to `git log --all` when commit ranges fail
+- **Solution**: Improve error handling to fail fast instead of using fallbacks
+
+#### 2. Parameter Validation
+
+- **Problem**: Workflow scripts accept unknown parameters silently
+- **Solution**: Use strict parameter validation with `zparseopts`
+
+### Lessons Learned
+
+1. **Always force push tags** after `git filter-repo`
+2. **Verify tag consistency** between local and remote
+3. **Add detection mechanisms** in workflows to catch history issues
+4. **Fail fast** when git history looks suspicious
+5. **Document expected commit counts** for validation
+6. **Use strict parameter validation** in all scripts
+
+### Future Improvements
+
+1. **Automated History Validation**: Add pre-commit hooks to detect history issues
+2. **Tag Synchronization**: Automate tag verification and updates
+3. **Workflow Monitoring**: Add alerts for unusual commit counts
+4. **Documentation Automation**: Auto-generate history change logs
+
+## References
+
+- [Git Filter-Repo Documentation](https://github.com/newren/git-filter-repo)
+- [GitHub Actions Checkout Action](https://github.com/actions/checkout)
+- [Git Force Push Considerations](https://git-scm.com/docs/git-push#Documentation/git-push.txt---force)