Release Production

Merge master (staging) into published (production) with proper changelog documentation.

Usage

/release-production

Workflow

Step 1: Pre-Flight Checks

Verify we're ready to release:

# Ensure we're in the main repo (not a worktree)
MAIN_REPO="$HOME/Development/VIPER/CoreApps/viper-metrics-v2-0"
cd "$MAIN_REPO"

# Fetch latest from remote
git fetch origin

# Check current branch
git branch --show-current

# Check for uncommitted changes
git status --porcelain

# Verify master and published are up to date
git log origin/master..master --oneline
git log origin/published..published --oneline

Validations:

• Must be in the main repo (not a worktree)
• No uncommitted changes
• Local branches in sync with remote

Step 2: Identify Changes for Release

Get all changes that will be released:

# Get commits on master that aren't in published
git log origin/published..origin/master --oneline

# Get the list of merged PRs
git log origin/published..origin/master --merges --oneline

# Get detailed info on PRs included
gh pr list --state merged --base master --json number,title,mergedAt,labels,author --jq '.[] | select(.mergedAt > "LAST_RELEASE_DATE")'

Create a summary of what's being released:

# Find all PRs merged since last release
# Look at the published branch's last commit date
LAST_RELEASE=$(git log origin/published -1 --format="%cI")

# Get PRs merged to master after that date
gh pr list --state merged --base master --json number,title,mergedAt,labels --jq "[.[] | select(.mergedAt > \"$LAST_RELEASE\")]"

Output a summary:

## Changes Ready for Release

Commits: {count} commits

PRs included:
| PR | Title | Type |
|----|-------|------|
| #123 | Fix login error | Bug Fix |
| #456 | Add bulk export | Feature |

Step 3: Check Documentation Status

For each PR being released, check if it needs documentation:

MAIN_REPO="$HOME/Development/VIPER/CoreApps/viper-metrics-v2-0"

# For each PR in the release
for PR in $PR_LIST; do
    # Get PR labels
    LABELS=$(gh pr view $PR --json labels --jq '.labels[].name')

    # Features (enhancement label) need documentation
    if echo "$LABELS" | grep -q "enhancement"; then
        # Check if documentation exists
        FEATURE_NAME=$(gh pr view $PR --json title --jq '.title' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')

        if [[ ! -f "$MAIN_REPO/wiki/features/$FEATURE_NAME.md" ]]; then
            echo "UNDOCUMENTED: PR #$PR needs documentation"
        fi
    fi
done

Three scenarios:

1. All features documented → Continue to Step 4
2. Features need documentation → Stop and prompt user
3. Bug fixes only → Continue (bugs don't need feature docs)

If undocumented features exist:

## Documentation Required

The following features need documentation before release:

| PR | Title | Status |
|----|-------|--------|
| #456 | Add bulk export | Needs documentation |
| #789 | Dark mode support | Needs documentation |

Options:
- Run /document-feature {pr_number} for each feature
- Or provide documentation manually

Re-run /release-production after documentation is complete.

Stop here if documentation is missing.

Step 4: Generate Changelog Entry

Create the changelog file:

MAIN_REPO="$HOME/Development/VIPER/CoreApps/viper-metrics-v2-0"
TODAY=$(date +%Y-%m-%d)
MONTH_YEAR=$(date +"%B %Y")

# Create changelog file
CHANGELOG_FILE="$MAIN_REPO/wiki/changelog/$TODAY-release.md"

Changelog content structure:

---
title: {Month Year} Release
date: {YYYY-MM-DD}
author: Jarred
status: published
tags:
  - changelog
---

# {Month Year} Release

**Release Date**: {Full Date}

## Summary

{2-3 sentence overview of what's in this release}

## New Features

- **Feature Name** ([#{pr_number}]({pr_url})): Description of the new feature and how to use it. See [[features/{feature-name}|documentation]].

## Improvements

- **Area improved** ([#{pr_number}]({pr_url})): What was improved and why it matters.

## Bug Fixes

| Issue | PR | Description |
|-------|-----|-------------|
| [#{issue}]({issue_url}) | [#{pr}]({pr_url}) | Brief description of what was fixed |

## Breaking Changes

{List any breaking changes, or "None" if none}

## Migration Notes

{Any steps users need to take, or "No user action required."}

---

[[changelog/README|Back to Changelog]]

Guidelines for changelog:

• Group PRs by type (Feature, Improvement, Bug Fix)
• Link to feature documentation for new features
• Include both issue and PR links for bug fixes
• Note any breaking changes prominently

Step 5: Review Changelog

Present the generated changelog to the user:

## Changelog Preview

I've generated the following changelog for this release:

{Show full changelog content}

Options:
- [Approve and continue] - Save changelog and proceed with merge
- [Edit changelog] - Make changes before saving
- [Cancel] - Don't release yet

If "Edit changelog": Allow user to provide edits, then regenerate.

Step 6: Save Changelog and Commit

MAIN_REPO="$HOME/Development/VIPER/CoreApps/viper-metrics-v2-0"
cd "$MAIN_REPO"

# Checkout master
git checkout master
git pull origin master

# Write changelog file
# (Use Write tool to create the file)

# Commit changelog
git add "wiki/changelog/$TODAY-release.md"
git commit -m "Add changelog for $TODAY release"
git push origin master

Step 7: Merge Master into Published

Perform the production merge:

MAIN_REPO="$HOME/Development/VIPER/CoreApps/viper-metrics-v2-0"
cd "$MAIN_REPO"

# Checkout published
git checkout published
git pull origin published

# Merge master into published
git merge origin/master --no-edit

# Push to remote
git push origin published

If merge conflicts:

## Merge Conflict

There are conflicts between master and published:

```
{list of conflicting files}
```

This usually shouldn't happen. Please resolve manually or investigate why the branches diverged.

Step 8: Tag the Release (Optional)

Ask user if they want to create a release tag:

Would you like to create a Git tag for this release?

- [Yes, create tag] - Create tag release-{date}
- [No, skip tag] - Continue without tagging

If yes:

TAG_NAME="release-$(date +%Y-%m-%d)"
git tag -a "$TAG_NAME" -m "Production release $(date +%Y-%m-%d)"
git push origin "$TAG_NAME"

Step 9: Session Complete

Output:

## Production Release Complete

Release Date: {date}

Changes Released:
- {X} commits
- {Y} bug fixes
- {Z} features

Changelog: wiki/changelog/{date}-release.md

Branches:
- master (staging) merged into published (production)

Tag: release-{date} (if created)

---

### What's Next

1. Verify production deployment in Anvil
2. Smoke test critical features
3. Monitor for errors

### Release Notes URL
{If you publish changelogs externally, include link}

Documentation Check Logic

Features require documentation; bug fixes don't:

Error Handling

Changelog Naming Convention

Files are named by release date:

wiki/changelog/
├── 2026-01-28-release.md
├── 2026-02-15-release.md
├── 2026-03-01-release.md
└── README.md

For multiple releases on the same day (rare):

wiki/changelog/
├── 2026-01-28-release.md
├── 2026-01-28-release-2.md  # Hotfix same day

Integration Points

Complete Release Workflow

[PRs merged to master]
    ↓
[Test in staging]
    ↓
/close-pr {numbers}        ← Close all issues for this release
    ↓
/release-production        ← This skill
    ↓
    ├── Check documentation status
    │   ├── If undocumented → /document-feature {pr}
    │   └── If documented → Continue
    ↓
    ├── Generate changelog
    ├── Merge master → published
    └── Push to production
    ↓
[Verify production deployment]

Guidelines

Always Document Features

• Features without documentation create confusion
• Documentation helps users understand new capabilities
• Changelog can reference feature docs for details

Write Clear Changelogs

• Summarize the "why" not just the "what"
• Group related changes together
• Highlight breaking changes prominently

Test Before Release

• All changes should be tested in staging
• Issues should be closed (verified working) before release
• Don't release untested changes

Keep Changelog History

• Never delete old changelog entries
• They serve as historical record
• Useful for tracking when changes were deployed