jass-learner/.claude/commands/version-helper.md

Version Helper Commands

Utility commands for version comparison and analysis in documentation sync workflows.

Git Commands for Version Analysis

Find Previous Version Tag

# Get all version tags sorted by version number
CURRENT_TAG="v1.1.4"
PREVIOUS_TAG=$(git tag --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | grep -v "$CURRENT_TAG" | tail -1)
echo "Comparing $PREVIOUS_TAG → $CURRENT_TAG"

Compare Versions

# Get changed files between versions
git diff --name-only $PREVIOUS_TAG..$CURRENT_TAG

# Focus on framework files
git diff --name-only $PREVIOUS_TAG..$CURRENT_TAG -- addons/card-framework/

# Get commit messages for changelog
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG

# Get detailed changes for specific files
git diff $PREVIOUS_TAG..$CURRENT_TAG -- addons/card-framework/

Change Categorization

# Categorize commits by conventional commit types
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG | grep -E '^[a-f0-9]+ feat:'    # New features
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG | grep -E '^[a-f0-9]+ fix:'     # Bug fixes  
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG | grep -E '^[a-f0-9]+ docs:'    # Documentation
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG | grep -E '^[a-f0-9]+ refactor:' # Refactoring
git log --oneline $PREVIOUS_TAG..$CURRENT_TAG | grep -E '^[a-f0-9]+ test:'    # Tests

Quick Sync Change Detection

# Working directory changes
git diff --name-only HEAD

# Staged changes
git diff --cached --name-only  

# Focus on API-affecting files
git diff --name-only HEAD -- addons/card-framework/ | grep '\.gd$'

# Check if any GDScript files changed
if git diff --name-only HEAD -- addons/card-framework/ | grep -q '\.gd$'; then
    echo "API files changed - documentation update needed"
fi

Claude Commands Integration

Full Sync Implementation

#!/bin/bash
# Implementation for /sync-docs command

CURRENT_TAG="$1"
PREVIOUS_TAG=$(git tag --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | grep -v "$CURRENT_TAG" | tail -1)

echo "📊 Analyzing changes from $PREVIOUS_TAG to $CURRENT_TAG"

# Get changed files
CHANGED_FILES=$(git diff --name-only $PREVIOUS_TAG..$CURRENT_TAG -- addons/card-framework/)

# Get commit messages for changelog
COMMITS=$(git log --oneline $PREVIOUS_TAG..$CURRENT_TAG)

# Pass to Claude for analysis
claude "/analyze addons/card-framework/ --focus api --persona-scribe=en --ultrathink --context '$CHANGED_FILES' --changelog-commits '$COMMITS'"

Quick Sync Implementation

#!/bin/bash
# Implementation for /quick-sync command

# Check for changes
WORKING_CHANGES=$(git diff --name-only HEAD -- addons/card-framework/ | grep '\.gd$' || true)
STAGED_CHANGES=$(git diff --cached --name-only -- addons/card-framework/ | grep '\.gd$' || true)

if [ -z "$WORKING_CHANGES" ] && [ -z "$STAGED_CHANGES" ]; then
    echo "✅ No API changes detected"
    exit 0
fi

echo "📝 Updating documentation for changed files:"
echo "$WORKING_CHANGES"
echo "$STAGED_CHANGES"

# Quick analysis of changed files only
claude "/analyze $WORKING_CHANGES $STAGED_CHANGES --focus api --persona-scribe=en --uc --incremental-update docs/API.md"

Version Tag Best Practices

Semantic Versioning

• v1.0.0 - Major version (breaking changes)
• v1.1.0 - Minor version (new features, backward compatible)
• v1.1.1 - Patch version (bug fixes)

Tagging Workflow

# Create and push tag
git tag v1.1.4 -m "Release version 1.1.4"
git push origin v1.1.4

# List all tags
git tag -l --sort=version:refname

# Get latest tag  
git describe --tags --abbrev=0

# Check if tag exists
git rev-parse --verify "refs/tags/v1.1.4" >/dev/null 2>&1

Error Handling

Common Issues

1. No previous tag found: Handle initial release case
2. Invalid tag format: Validate semantic versioning
3. Empty diff: Handle no changes between versions
4. Tag doesn't exist: Verify tag before processing

Fallback Strategies

# If no previous tag, use initial commit
PREVIOUS_TAG=${PREVIOUS_TAG:-$(git rev-list --max-parents=0 HEAD)}

# If current tag doesn't exist, use HEAD
CURRENT_TAG=${CURRENT_TAG:-"HEAD"}

# Validate tag format
if [[ ! "$CURRENT_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "Warning: Tag format should be vX.Y.Z"
fi