Automated RELEASE NOTES and Changelog w/ Actions

see .github/RELEASE_AUTOMATION.md for details

Though GitHub Actions, we integrated automatic Changelog and RELEASE
NOTES generation.

For pull requests and commits.

Author: freephile

.github/RELEASE_AUTOMATION.md

@@ -0,0 +1,278 @@
+# Automated Release Management
+
+This document describes the GitHub Actions workflows available for automated release notes generation and changelog management.
+
+## 🚀 Available Workflows
+
+### 1. Basic Release Notes (`release-notes.yml`)
+
+**Triggers:**
+- Push to `main`, `dev`, `develop`
+- Pull requests to `main`, `dev`, `develop`
+
+**Features:**
+- ✅ Automatic CHANGELOG updates
+- ✅ Release notes generation 
+- ✅ Smart change detection (only runs if needed)
+- ✅ Direct commits to main branch
+- ✅ Pull requests for other branches
+
+**What it does:**
+- Detects new commits since last CHANGELOG update
+- Updates `CHANGELOG` using `updateCHANGELOG.sh`
+- Generates `RELEASE_NOTES-HEAD.md` from tag `43.0.0` to `HEAD`
+- Commits changes automatically or creates PR
+
+### 2. Advanced Release Management (`advanced-release-management.yml`)
+
+**Triggers:**
+- Push to `main`, `dev`
+- Tag pushes (version tags)
+- Manual dispatch with options
+
+**Advanced Features:**
+- 🏷️ Automatic GitHub releases for tags
+- 🔄 Version range detection
+- ⚙️ Force update option
+- 📊 Detailed job summaries
+- 🎯 Smart tag-based release notes
+
+**Manual Trigger Options:**
+- `force_update`: Force update even if no changes detected
+- `version_tag`: Specific version tag to generate release notes for
+
+### 3. Manual Release Notes Generator (`manual-release-notes.yml`)
+
+**Triggers:**
+- Manual dispatch only
+
+**Full Control Features:**
+- 📝 Custom commit range selection
+- 🎛️ Optional CHANGELOG updates  
+- 📋 Artifact generation
+- 🔍 Commit validation
+- 📊 Detailed analysis
+
+**Manual Parameters:**
+- `start_ref`: Start reference (tag, branch, or commit)
+- `end_ref`: End reference (tag, branch, or commit)
+- `update_changelog`: Whether to update CHANGELOG
+
+## 📖 Usage Guide
+
+### Automatic Usage
+
+Most workflows run automatically:
+
+```yaml
+# Triggered on every push to main/dev
+git push origin main
+
+# Triggered on PR creation
+gh pr create --title "New feature" --body "Description"
+
+# Triggered on tag creation  
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+### Manual Triggers
+
+#### Quick Force Update
+```bash
+# Via GitHub CLI
+gh workflow run "Advanced Release Management" \
+  --field force_update=true
+
+# Via GitHub Web UI
+# Go to Actions > Advanced Release Management > Run workflow
+# Check "Force update" and click "Run workflow"
+```
+
+#### Custom Range Release Notes
+```bash
+# Generate release notes for specific range
+gh workflow run "Manual Release Notes Generator" \
+  --field start_ref="v1.2.0" \
+  --field end_ref="v1.3.0" \
+  --field update_changelog=true
+
+# Generate from last 10 commits
+gh workflow run "Manual Release Notes Generator" \
+  --field start_ref="HEAD~10" \
+  --field end_ref="HEAD" \
+  --field update_changelog=false
+```
+
+## 📁 Generated Files
+
+| File | Description | Generated By |
+|------|-------------|--------------|
+| `CHANGELOG` | Raw git log format | `updateCHANGELOG.sh` |
+| `RELEASE_NOTES-HEAD.md` | Current development notes | All workflows |
+| `RELEASE_NOTES-{tag}.md` | Tagged release notes | Advanced/Manual workflows |
+
+## 🔧 Configuration
+
+### Baseline Configuration
+- **Default Start Tag**: `43.0.0` - All automatic release notes start from this baseline
+- **Range**: Release notes cover `43.0.0` → `HEAD` by default
+- **Customization**: Modify `START_TAG="43.0.0"` in workflow files to change baseline
+
+### Environment Variables
+- `GITHUB_TOKEN`: Automatically provided (no setup needed)
+
+### Permissions Required
+```yaml
+permissions:
+  contents: write      # For committing changes
+  pull-requests: write # For creating PRs
+  issues: write        # For linking issues (advanced workflow)
+```
+
+### Branch Protection
+Workflows respect branch protection rules:
+- **Protected branches**: Creates pull requests
+- **Unprotected branches**: Direct commits
+
+## 📋 Best Practices
+
+### For Development
+1. **Let automatic workflows handle routine updates**
+   - Push to `dev` branch triggers automatic updates
+   - Review generated content in pull requests
+
+2. **Use manual triggers for special cases**
+   - Generating historical release notes
+   - Creating release notes for specific ranges
+   - Force updates when automatic detection fails
+
+### For Releases
+1. **Tag-based releases are automated**
+   ```bash
+   git tag v1.2.3
+   git push origin v1.2.3
+   # → Automatic GitHub release created
+   ```
+
+2. **Manual release preparation**
+   ```bash
+   # Generate release notes before tagging
+   gh workflow run "Manual Release Notes Generator" \
+     --field start_ref="v1.2.0" \
+     --field end_ref="HEAD"
+   ```
+
+### For Maintenance
+1. **Regular CHANGELOG cleanup**
+   - Automatic updates keep CHANGELOG current
+   - Manual review recommended for major releases
+
+2. **Historical documentation**
+   - Use manual workflow to generate missing release notes
+   - Maintain consistent formatting across versions
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**Workflow doesn't trigger:**
+- Check branch names match trigger conditions
+- Verify repository permissions
+- Ensure `GITHUB_TOKEN` has necessary permissions
+
+**No changes detected:**
+- Verify commits exist in specified range
+- Check if CHANGELOG is already up to date
+- Use `force_update=true` for manual override
+
+**Linting failures:**
+- Workflows run linting before committing
+- Fix YAML syntax errors in generated files
+- Check `lint-files.sh` output for details
+
+**Permission denied:**
+- Verify workflow has `contents: write` permission
+- Check branch protection settings
+- Ensure GitHub token has necessary scope
+
+### Debug Steps
+
+1. **Check workflow logs:**
+   ```bash
+   gh run list --workflow="release-notes.yml"
+   gh run view [run-id] --log
+   ```
+
+2. **Test locally:**
+   ```bash
+   # Test changelog update
+   ./src/scripts/updateCHANGELOG.sh
+   
+   # Test release notes generation (same as workflow)
+   ./src/scripts/generate-release-notes.sh 43.0.0 HEAD
+   
+   # Test with recent commits only
+   ./src/scripts/generate-release-notes.sh HEAD~5 HEAD
+   ```
+
+3. **Validate references:**
+   ```bash
+   # Check if ref exists
+   git rev-parse --verify HEAD~10
+   
+   # Check commit range
+   git log --oneline HEAD~10..HEAD
+   ```
+
+## 🔗 Related Documentation
+
+- [`updateCHANGELOG.sh`](../src/scripts/updateCHANGELOG.sh) - CHANGELOG update script
+- [`generate-release-notes.sh`](../src/scripts/generate-release-notes.sh) - Release notes generator  
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Meza Release Process](https://wiki.freephile.org/wiki/RELEASE_NOTES)
+
+## 📝 Examples
+
+### Typical Workflow
+
+```bash
+# 1. Development work
+git checkout dev
+git commit -m "Add new feature"
+git push origin dev
+# → Automatic CHANGELOG/release notes update via PR
+
+# 2. Merge to main  
+git checkout main
+git merge dev
+git push origin main
+# → Direct commit with updated documentation (43.0.0 → HEAD)
+
+# 3. Create release
+git tag 43.58.0
+git push origin 43.58.0
+# → Automatic GitHub release with release notes
+```
+
+### Manual Release Notes for Historical Versions
+
+```bash
+# Generate release notes between two tags
+gh workflow run "Manual Release Notes Generator" \
+  --field start_ref="43.0.0" \
+  --field end_ref="43.57.1" \
+  --field update_changelog=false
+
+# Generate from baseline tag to HEAD (same as automatic workflow)
+gh workflow run "Manual Release Notes Generator" \
+  --field start_ref="43.0.0" \
+  --field end_ref="HEAD" \
+  --field update_changelog=true
+
+# Generate from first commit to baseline tag (historical)
+gh workflow run "Manual Release Notes Generator" \
+  --field start_ref="$(git rev-list --max-parents=0 HEAD)" \
+  --field end_ref="43.0.0" \
+  --field update_changelog=false
+```