aidevops 2.52.1

package/.agent/workflows/release.md

@@ -0,0 +1,498 @@
+---
+description: Full release workflow with version bump, tag, and GitHub release
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Release Workflow
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Full release**: `.agent/scripts/version-manager.sh release [major|minor|patch] --skip-preflight`
+- **CRITICAL**: Always use the script above - it updates all 6 version files atomically
+- **NEVER** manually edit VERSION, bump versions yourself, or use separate commands
+
+**Before releasing**: Check for uncommitted changes and commit them first:
+
+```bash
+git status --short  # Check for uncommitted changes
+git add -A && git commit -m "feat: description of changes"  # Commit if needed
+```
+
+- **Auto-changelog**: Release script auto-generates CHANGELOG.md from conventional commits
+- **Create tag**: `.agent/scripts/version-manager.sh tag`
+- **GitHub release**: `.agent/scripts/version-manager.sh github-release`
+- **Postflight**: `.agent/scripts/postflight-check.sh` (verify after release)
+- **Deploy locally**: `./setup.sh` (aidevops repo only - deploys to ~/.aidevops/agents/)
+- **Validator**: `.agent/scripts/validate-version-consistency.sh`
+- **GitHub Actions**: `.github/workflows/version-validation.yml`
+- **Version bump only**: See `workflows/version-bump.md`
+- **Changelog format**: See `workflows/changelog.md`
+- **Postflight verification**: See `workflows/postflight.md` (verify after release)
+
+<!-- AI-CONTEXT-END -->
+
+This workflow covers the release process: tagging, pushing, and creating GitHub/GitLab releases. For version number management only, see `workflows/version-bump.md`. For changelog format and validation, see `workflows/changelog.md`. For PR-based merges before release, see `workflows/pr.md`.
+
+## Pre-Release Checklist
+
+Before running the release command:
+
+- [ ] All working changes committed (no uncommitted files)
+- [ ] Tests passing
+- [ ] CHANGELOG.md has unreleased content (or use `--force`)
+
+The release script will **refuse to release** if there are uncommitted changes.
+This prevents accidentally releasing without your session's work.
+
+## Merging Work Branch to Main
+
+Before releasing, merge your work branch to main (or create PR/MR if collaborating):
+
+### Direct Merge (Solo Work)
+
+```bash
+# 1. Ensure branch is up to date
+git checkout {your-branch}
+git fetch origin
+git rebase origin/main  # or merge
+
+# 2. Switch to main and merge
+git checkout main
+git pull origin main
+git merge --no-ff {your-branch} -m "Merge {your-branch} into main"
+
+# 3. Push merged main
+git push origin main
+
+# 4. Delete branch after merge
+git branch -d {your-branch}
+git push origin --delete {your-branch}
+```
+
+### PR/MR Workflow (Collaborative)
+
+When working with others or requiring review:
+
+```bash
+# 1. Push branch
+git push -u origin {your-branch}
+
+# 2. Create PR/MR
+gh pr create --fill --base main  # GitHub
+glab mr create --fill --target-branch main  # GitLab
+
+# 3. After approval and merge, continue with release
+git checkout main
+git pull origin main
+```
+
+### Decision Tree
+
+| Situation | Action |
+|-----------|--------|
+| Solo work, simple changes | Direct merge to main |
+| Team collaboration | Create PR/MR for review |
+| Multiple branches to release | Merge each to main, then release |
+| Hotfix on production | Use `hotfix/` branch, merge to main + release |
+| Parallel sessions, same feature | Coordinate via PR to avoid conflicts |
+
+## Release Workflow Overview
+
+The release script handles everything automatically:
+
+1. **Check for uncommitted changes** (fails if dirty, use `--allow-dirty` to bypass)
+2. Bump version in all files (VERSION, README.md, setup.sh, sonar-project.properties, package.json, .claude-plugin/marketplace.json)
+3. **Auto-generate CHANGELOG.md** from conventional commits
+4. Validate version consistency
+5. Commit all changes
+6. Create version tag
+7. Push to remote
+8. Create GitHub release
+9. Post-release verification
+
+## Quick Release (aidevops)
+
+**MANDATORY**: Use this single command for ALL releases:
+
+```bash
+./.agent/scripts/version-manager.sh release [major|minor|patch] --skip-preflight
+```
+
+**Flags**:
+- `--skip-preflight` - Skip linting checks (faster)
+- `--force` - Bypass empty changelog check
+- `--allow-dirty` - Release with uncommitted changes (not recommended)
+
+This command:
+1. Checks for uncommitted changes (fails if dirty)
+2. Bumps version in all 6 files atomically (VERSION, README.md, setup.sh, sonar-project.properties, package.json, .claude-plugin/marketplace.json)
+3. **Auto-generates CHANGELOG.md** from conventional commits (feat:, fix:, docs:, etc.)
+4. Validates consistency
+5. Commits version bump + changelog
+6. Creates git tag
+7. Pushes to remote
+8. Creates GitHub release
+
+**DO NOT** run separate bump/tag/push commands - use this single command only.
+
+## Auto-Changelog Generation
+
+The release script automatically generates changelog entries from conventional commits:
+
+| Commit Type | Changelog Section |
+|-------------|-------------------|
+| `feat:` | Added |
+| `fix:` | Fixed |
+| `docs:` | Changed (Documentation) |
+| `refactor:` | Changed (Refactor) |
+| `perf:` | Changed (Performance) |
+| `security:` | Security |
+| `BREAKING CHANGE:` | Removed (BREAKING) |
+| `deprecate:` | Deprecated |
+
+Commits with `chore:` prefix are excluded from the changelog.
+
+**Best practice**: Use conventional commit messages for accurate changelog generation:
+
+```bash
+git commit -m "feat: add DataForSEO MCP integration"
+git commit -m "fix: resolve Serper API authentication"
+git commit -m "docs: update release workflow documentation"
+```
+
+## Detailed Release Steps
+
+### 1. Create a Release Branch (Optional)
+
+For larger projects, create a release branch:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b release/v{MAJOR}.{MINOR}.{PATCH}
+```
+
+### 2. Run Code Quality Checks
+
+```bash
+# For this framework
+./.agent/scripts/linters-local.sh
+
+# Generic checks
+npm run lint && npm test
+flake8 . && pytest
+go vet ./... && go test ./...
+```
+
+### 3. Changelog (Auto-Generated)
+
+The release script **automatically generates** CHANGELOG.md entries from conventional commits. No manual changelog editing required.
+
+```bash
+# Preview what will be generated (optional)
+./.agent/scripts/version-manager.sh changelog-preview
+
+# Validate existing changelog (optional)
+./.agent/scripts/version-manager.sh changelog-check
+```
+
+The auto-generated changelog follows [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- Feature from feat: commits
+
+### Changed
+- Changes from docs:, refactor:, perf: commits
+
+### Fixed
+- Fixes from fix: commits
+```
+
+See `workflows/changelog.md` for manual changelog guidance if needed.
+
+### 4. Commit Version Changes
+
+```bash
+git add -A
+git commit -m "chore(release): prepare v{MAJOR}.{MINOR}.{PATCH}"
+```
+
+### 5. Create Version Tags
+
+```bash
+# Using version-manager (preferred)
+./.agent/scripts/version-manager.sh tag
+
+# Or manually
+git tag -a v{VERSION} -m "Release v{VERSION}"
+```
+
+### 6. Push to Remote
+
+```bash
+git push origin main
+git push origin --tags
+
+# For multiple remotes
+git push github main --tags
+git push gitlab main --tags
+```
+
+### 7. Create GitHub/GitLab Release
+
+**Using version-manager (preferred):**
+
+```bash
+./.agent/scripts/version-manager.sh github-release
+```
+
+**Using GitHub CLI:**
+
+```bash
+gh release create v{VERSION} \
+  --title "v{VERSION}" \
+  --notes-file RELEASE_NOTES.md \
+  ./dist/*
+```
+
+**Using GitLab CLI:**
+
+```bash
+glab release create v{VERSION} \
+  --name "v{VERSION}" \
+  --notes-file RELEASE_NOTES.md
+```
+
+## GitHub Integration
+
+### Authentication Methods
+
+**1. GitHub CLI (Preferred):**
+
+```bash
+brew install gh  # macOS
+gh auth login
+```
+
+**2. GitHub API (Fallback):**
+
+```bash
+export GITHUB_TOKEN=your_personal_access_token
+```
+
+### GitHub Actions Automation
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: npm run build
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true
+```
+
+## Post-Release Tasks
+
+### Deploy Updated Agents (aidevops repo only)
+
+> **Skip this section** if releasing any repo other than `~/Git/aidevops`.
+
+After releasing the aidevops framework itself, re-run setup.sh to deploy locally:
+
+```bash
+cd ~/Git/aidevops && ./setup.sh
+```
+
+This ensures `~/.aidevops/agents/` has the latest release with updated version references.
+
+### Task Completion
+
+Mark all tasks included in this release as completed:
+
+1. **Move tasks** from `## In Progress` or `## In Review` to `## Done`
+2. **Add timestamps**: `completed:` with current date
+3. **Add actual time**: `actual:` if known (calculate from `started:`)
+4. **Sync with Beads**
+
+```markdown
+# Before (in ## In Progress or ## In Review)
+- [ ] t001 Add user dashboard #feature ~4h started:2025-01-15T10:30Z
+
+# After (move to ## Done)
+- [x] t001 Add user dashboard #feature ~4h actual:5h30m started:2025-01-15T10:30Z completed:2025-01-16T14:00Z
+```
+
+```bash
+# Sync with Beads after updating TODO.md
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+```
+
+**Task identification**: The release script can parse commit messages for task IDs:
+- Conventional commits: `feat(t001): add user dashboard`
+- Issue references: `Closes #123` (if linked to task)
+
+### Time Summary
+
+After release, update TODO.md and PLANS.md with actual time spent:
+
+```markdown
+# Update completed tasks with actual: field
+# Before: - [x] Add user dashboard #feature ~4h started:2025-01-15T10:30Z completed:2025-01-16T14:00Z
+# After:  - [x] Add user dashboard #feature ~4h actual:5h30m started:2025-01-15T10:30Z completed:2025-01-16T14:00Z
+```
+
+**Time summary report** (generated at release):
+
+```markdown
+## Release v1.2.0 Time Summary
+
+| Task | Estimated | Actual | Variance |
+|------|-----------|--------|----------|
+| Add user dashboard | 4h | 5h30m | +1h30m |
+| Fix login timeout | 2h | 1h45m | -15m |
+| **Total** | **6h** | **7h15m** | **+1h15m** |
+
+Estimation accuracy: 83%
+```
+
+The release script can optionally generate this summary from TODO.md TOON blocks.
+
+### Postflight Verification
+
+After release publication, run postflight checks to verify release health:
+
+```bash
+# Run full postflight verification
+./.agent/scripts/postflight-check.sh
+
+# Quick check (CI/CD + SonarCloud only)
+./.agent/scripts/postflight-check.sh --quick
+
+# Or check CI/CD manually
+gh run watch $(gh run list --limit=1 --json databaseId -q '.[0].databaseId') --exit-status
+```
+
+See `workflows/postflight.md` for detailed verification procedures and rollback guidance.
+
+### Immediate
+
+1. Run postflight verification (see above)
+2. Verify release artifacts and download links
+3. Update documentation site
+4. Notify stakeholders
+5. Monitor for issues
+
+### Follow-up
+
+1. Update dependent projects
+2. Close release milestone
+3. Start next version planning
+4. Update roadmap
+
+## Rollback Procedures
+
+### Identify the Issue
+
+```bash
+git log --oneline -10
+git diff v{PREVIOUS} v{CURRENT}
+```
+
+### Create Hotfix
+
+```bash
+git checkout -b hotfix/v{NEW_PATCH}
+# Fix the issue
+git commit -m "fix: resolve critical issue"
+```
+
+### Or Revert
+
+```bash
+git revert <commit-hash>
+git commit -m "revert: rollback v{CURRENT}"
+```
+
+## Troubleshooting
+
+### Tag Already Exists
+
+```bash
+git tag -d v{VERSION}
+git push origin --delete v{VERSION}
+git tag -a v{VERSION} -m "Release v{VERSION}"
+git push origin v{VERSION}
+```
+
+### GitHub CLI Not Authenticated
+
+```bash
+gh auth login
+```
+
+### GitHub Token Issues
+
+```bash
+# Check token permissions (needs 'repo' scope)
+curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
+```
+
+### Version Mismatch
+
+```bash
+# Validate consistency
+./.agent/scripts/version-manager.sh validate
+
+# See version-bump.md for fixing
+```
+
+## Release Types
+
+See `workflows/version-bump.md` for semantic versioning rules (major/minor/patch). Hotfixes follow patch versioning with an expedited release process.
+
+## Release Communication Template
+
+```markdown
+# [Project Name] v{X.Y.Z} Released
+
+## Highlights
+- Feature 1: Description
+- Feature 2: Description
+
+## Breaking Changes
+- Description of any breaking changes
+
+## Upgrade Guide
+1. Step to upgrade
+2. Migration notes
+
+## Full Changelog
+See [CHANGELOG.md](link) for complete details.
+```