name: git.release.prep description: Prepare releases with semantic versioning, changelog generation, git tags, GitHub releases, and deployment bundle creation.

git.release.prep

Purpose

This skill automates release preparation for Carbon ACX by:

Determining next version using semantic versioning (semver)
Generating/updating CHANGELOG with categorized changes
Creating annotated git tags
Generating GitHub release notes
Building deployment bundles (make package or equivalent)
Verifying builds succeed before tagging
Publishing GitHub releases with artifacts

When to Use

Trigger Patterns:

"Prepare a release"
"Create release v1.2.3"
"Tag a new version"
"Publish a release"
After merging significant features to main
When ready to deploy new dataset version (ACX042, etc.)

Do NOT Use When:

Still in active development (not ready to release)
Tests are failing
Build is broken
On a feature branch (releases should be from main/master)

Allowed Tools

bash - Git commands, build commands, gh CLI
read_file - Read CHANGELOG, version files, package.json
write_file - Update CHANGELOG, version files
edit_file - Modify existing CHANGELOG entries

Access Level: 3 (Can modify files, create tags, publish releases)

Tool Rationale:

bash: Required for git tagging, building, gh CLI
read_file: Read current versions and changelogs
write_file/edit_file: Update version files and changelog

Explicitly Denied:

No force pushing tags
No deleting existing tags without explicit approval
No deploying to production (separate deployment workflow)

Expected I/O

Input:

Type: Release preparation request
Context: Branch ready for release (usually main/master)
Optional: Version number (e.g., "v1.2.3" or "ACX042")
Optional: Release type (major, minor, patch)

Example:

"Prepare release v1.3.0"
"Create a patch release"
"Tag dataset version ACX042"

Output:

Type: Release prepared and published
Format: Git tag + GitHub release URL
Includes:
- Version number used
- CHANGELOG updates
- Build artifacts bundled
- GitHub release created
- Next steps (deployment instructions)

Validation:

Version follows semver (MAJOR.MINOR.PATCH)
CHANGELOG updated with categorized changes
Build succeeds before tagging
Git tag created and pushed
GitHub release published with notes

Dependencies

Required:

Git repository on main/master branch
gh CLI installed and authenticated
Build system working (make package or equivalent)
CHANGELOG file exists (or will be created)

Optional:

package.json for Node.js version (web apps)
pyproject.toml for Python version (calc engine)
calc/outputs/sprint_status.txt for dataset versions

Carbon ACX Specifics:

Dataset releases use ACX### format (ACX041, ACX042, etc.)
Code releases use semver vMAJOR.MINOR.PATCH
Both may happen in single release

Workflow

Step 1: Determine Current Version

Check multiple sources:

# Git tags
git describe --tags --abbrev=0 2>/dev/null

# package.json (if exists)
cat package.json | grep '"version"'

# pyproject.toml (if exists)
cat pyproject.toml | grep '^version'

# Dataset version
cat calc/outputs/sprint_status.txt 2>/dev/null

Parse version: Extract MAJOR.MINOR.PATCH Examples:

v1.2.3 → major=1, minor=2, patch=3
ACX041 → dataset version 41

Step 2: Determine Next Version

Semantic Versioning Rules:

MAJOR (v2.0.0): Breaking changes, incompatible API changes
MINOR (v1.3.0): New features, backwards-compatible
PATCH (v1.2.4): Bug fixes, backwards-compatible

Heuristic (if user doesn't specify):

Check commits since last release:
```
git log v1.2.3...HEAD --oneline
```
Analyze commit types:
- Any BREAKING CHANGE: or ! → MAJOR
- Any feat: commits → MINOR
- Only fix:, chore:, docs: → PATCH

Dataset Versions:

Increment by 1: ACX041 → ACX042
Update calc/outputs/sprint_status.txt

User can override: "Create major release v2.0.0"

Step 3: Generate CHANGELOG

Read commits since last release:

git log v1.2.3...HEAD --pretty=format:"%s (%h)"

Categorize commits:

Features: feat: commits
Fixes: fix: commits
Chores: chore:, refactor:, style:, perf:
Documentation: docs: commits
Breaking Changes: Any with BREAKING CHANGE: or !

CHANGELOG format (append to existing file):

## [1.3.0] - 2025-10-24

### Features
- Add dark mode toggle to dashboard (a1b2c3d)
- Implement emission chart component (d4e5f6g)
- Support CSV export for reports (g7h8i9j)

### Fixes
- Correct aviation emission factor calculation (j0k1l2m)
- Fix responsive layout on mobile (n3o4p5q)

### Chores
- Update React to 18.3.1 (r6s7t8u)
- Refactor component directory structure (v9w0x1y)

### Documentation
- Add theming guide to docs (z2a3b4c)

If CHANGELOG doesn't exist, create with header:

# Changelog

All notable changes to Carbon ACX will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.3.0] - 2025-10-24
...

Step 4: Update Version Files

package.json (if exists):

{
  "version": "1.3.0"
}

pyproject.toml (if exists):

[tool.poetry]
version = "1.3.0"

calc/outputs/sprint_status.txt (dataset):

ACX042

Commit version updates:

git add CHANGELOG.md package.json pyproject.toml calc/outputs/sprint_status.txt
git commit -m "chore: prepare release v1.3.0

Updates version files and CHANGELOG for v1.3.0 release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Step 5: Build and Verify

# Run build
make build || pnpm build

# Run tests
make validate || pnpm test

# Create deployment bundle
make package

Verification:

✅ Build succeeds without errors
✅ Tests pass
✅ Package created in dist/ or equivalent

If build fails: Stop, report error, do NOT create tag

Step 6: Create Git Tag

Annotated tag with message:

git tag -a v1.3.0 -m "Release v1.3.0

Features:
- Dark mode toggle
- Emission chart component
- CSV export

Fixes:
- Aviation emission factor calculation
- Mobile responsive layout

See CHANGELOG.md for full details."

Push tag:

git push origin v1.3.0

Also push commit:

git push origin main

Step 7: Create GitHub Release

Generate release notes from CHANGELOG: Extract the section for this version from CHANGELOG.md

Create release with gh CLI:

gh release create v1.3.0 \
  --title "Release v1.3.0" \
  --notes "$(cat <<'EOF'
## Features
- Add dark mode toggle to dashboard
- Implement emission chart component
- Support CSV export for reports

## Fixes
- Correct aviation emission factor calculation
- Fix responsive layout on mobile

## Chores
- Update React to 18.3.1
- Refactor component directory structure

## Documentation
- Add theming guide to docs

See [CHANGELOG.md](https://github.com/owner/carbon-acx/blob/main/CHANGELOG.md) for full details.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Attach artifacts (if applicable):

gh release upload v1.3.0 dist/site.tar.gz dist/artifacts.zip

Step 8: Report Success

Output to user:

✅ Release v1.3.0 Prepared

Version: v1.3.0 (from v1.2.3)
Type: Minor release
Commits: 12 commits since last release

Changes:
- 4 features
- 2 bug fixes
- 3 chores
- 1 documentation update

Artifacts:
✅ CHANGELOG.md updated
✅ Version files updated
✅ Build succeeded
✅ Tests passed
✅ Git tag created: v1.3.0
✅ Tag pushed to origin
✅ GitHub release created

Release URL: https://github.com/owner/carbon-acx/releases/tag/v1.3.0

Next Steps:
- Deploy to staging: [deployment command]
- Test in staging environment
- Deploy to production when ready
- Announce release to users

Examples

Example 1: Minor Release

User: "Prepare release v1.3.0"

Claude Process:

Verify current version: v1.2.3 (from git tags)
Analyze commits: 12 commits with feat, fix, chore types
Generate CHANGELOG section for v1.3.0
Update package.json version to 1.3.0
Commit version updates
Run make build - succeeds ✅
Run make validate - passes ✅
Create tag: git tag -a v1.3.0 -m "..."
Push tag: git push origin v1.3.0
Create GitHub release with notes
Attach dist/site.tar.gz as artifact
Report success with URL

Example 2: Patch Release

User: "Create a patch release"

Claude Process:

Current version: v1.2.3
Analyze commits: Only bug fixes, no features
Next version: v1.2.4 (patch bump)

Generate CHANGELOG:

## [1.2.4] - 2025-10-24

### Fixes
- Fix memory leak in chart rendering (a1b2c3d)
- Correct date formatting in reports (d4e5f6g)

Update version files to 1.2.4
Build and test
Tag v1.2.4
Create GitHub release
Report: "Patch release v1.2.4 created"

Example 3: Major Release (Breaking Changes)

User: "Prepare major release v2.0.0"

Claude Process:

Current version: v1.5.3
User specified MAJOR bump

Check commits for breaking changes:

feat!: redesign API endpoints
BREAKING CHANGE: /api/v1/* endpoints removed

Generate CHANGELOG with prominent breaking changes section:

## [2.0.0] - 2025-10-24

### ⚠️ BREAKING CHANGES
- API endpoints redesigned - /api/v1/* removed
- Minimum Node.js version now 20.x
- CSV schema updated - requires migration

### Features
- New API v2 with improved performance
- GraphQL support

### Migration Guide
See docs/MIGRATION_v2.md for upgrade instructions

Update version to 2.0.0
Build and test thoroughly
Tag v2.0.0 with detailed message
Create GitHub release marking as major version
Warn user: "This is a MAJOR release with breaking changes"

Example 4: Dataset Release

User: "Tag dataset version ACX042"

Claude Process:

Read current dataset version: ACX041
Next version: ACX042
Update calc/outputs/sprint_status.txt to ACX042
Check what data changed:
```
git diff ACX041...HEAD -- data/
```

Generate dataset-specific CHANGELOG:

## Dataset ACX042 - 2025-10-24

### Data Updates
- Updated grid intensity factors for Q4 2024
- Added 15 new activities in professional services layer
- Corrected emission factors for aviation (long-haul)

### Schema Changes
- Added `data_vintage` column to emission_factors.csv

### Validation
- All integrity checks pass
- Manifest hashes regenerated

Rebuild dataset: make build
Tag: git tag -a ACX042 -m "Dataset release ACX042"
Create GitHub release with dataset artifacts
Attach manifest files

Example 5: Combined Code + Dataset Release

User: "Prepare release with code v1.4.0 and dataset ACX042"

Claude Process:

Dual versioning:
- Code: v1.3.1 → v1.4.0
- Dataset: ACX041 → ACX042

Generate combined CHANGELOG:

## [v1.4.0 / ACX042] - 2025-10-24

### Code Changes
#### Features
- Add new visualization for grid intensity

### Dataset Changes
- Dataset version ACX041 → ACX042
- Updated grid intensity factors
- Added 15 new activities

Update both version files
Rebuild everything: make build && make package
Create tag: v1.4.0-ACX042
GitHub release notes include both code and data changes
Attach both code bundle and dataset artifacts

Limitations

Scope Limitations:

Cannot automatically deploy to production (separate process)
Cannot delete or modify existing releases without approval
Cannot create releases on branches other than main/master
Requires manual verification that changes are release-ready

Known Edge Cases:

First release (no previous tags) → Start at v1.0.0 or v0.1.0
Unreleased commits on main → Ask user if intentional or accidental
Build failures → Stop process, report error, do NOT tag
Conflicting version numbers → Ask user which to use

Performance Constraints:

Large builds (webpack, packaging) may take 2-5 minutes
Many commits (100+) slow CHANGELOG generation
Large artifacts may fail to upload (GitHub limit: 2GB per file)

Security Boundaries:

Does not auto-approve releases (human must verify)
Does not skip tests or builds
Does not force push tags
Respects branch protection rules

Validation Criteria

Success Metrics:

✅ Version follows semver (or dataset versioning)
✅ CHANGELOG updated with categorized changes
✅ Version files updated consistently
✅ Build succeeded before tagging
✅ Tests passed before tagging
✅ Git tag created with proper message
✅ Tag pushed to remote
✅ GitHub release created with notes
✅ Artifacts attached (if applicable)
✅ User informed of release URL

Failure Modes:

❌ Build fails → Stop, report error, do NOT tag
❌ Tests fail → Stop, suggest fixing tests first
❌ Not on main/master → Warn, suggest merging to main first
❌ Uncommitted changes → Ask user to commit or stash
❌ Tag already exists → Ask if should overwrite or increment

Recovery:

If build fails: Report error logs, suggest fixes
If tag conflicts: Suggest alternative version number
If GitHub release fails: Provide manual creation instructions
If uncertain about version bump: Ask user to specify

Composes With:

git.commit.smart - Commit version updates before tagging
git.pr.create - Create release PR for review before tagging
carbon.data.qa - Verify dataset changes before release

Dependencies:

Git repository on releasable branch
Build system functional

Alternative Skills:

For commits: git.commit.smart
For PRs: git.pr.create

Maintenance

Owner: Workspace Team (shared skill) Review Cycle: Quarterly (or before each major release) Last Updated: 2025-10-24 Version: 1.0.0

Maintenance Notes:

Update CHANGELOG format if Carbon ACX adopts different style
Adjust semver rules if project changes versioning scheme
Review artifact packaging as build process evolves
Keep dataset versioning logic synchronized with actual practice

gitreleaseprep

SKILL.md

name: git.release.prep description: Prepare releases with semantic versioning, changelog generation, git tags, GitHub releases, and deployment bundle creation.

git.release.prep

Purpose

When to Use

Allowed Tools

Expected I/O

Dependencies

Workflow

Step 1: Determine Current Version

Step 2: Determine Next Version

Step 3: Generate CHANGELOG

Step 4: Update Version Files

Step 5: Build and Verify

Step 6: Create Git Tag

Step 7: Create GitHub Release

Step 8: Report Success

Examples

Example 1: Minor Release

Example 2: Patch Release

Example 3: Major Release (Breaking Changes)

Example 4: Dataset Release

Example 5: Combined Code + Dataset Release

Limitations

Validation Criteria

Maintenance

Score

Reviews

gitreleaseprep

SKILL.md

name: git.release.prep description: Prepare releases with semantic versioning, changelog generation, git tags, GitHub releases, and deployment bundle creation.

git.release.prep

Purpose

When to Use

Allowed Tools

Expected I/O

Dependencies

Workflow

Step 1: Determine Current Version

Step 2: Determine Next Version

Step 3: Generate CHANGELOG

Step 4: Update Version Files

Step 5: Build and Verify

Step 6: Create Git Tag

Step 7: Create GitHub Release

Step 8: Report Success

Examples

Example 1: Minor Release

Example 2: Patch Release

Example 3: Major Release (Breaking Changes)

Example 4: Dataset Release

Example 5: Combined Code + Dataset Release

Limitations

Validation Criteria

Related Skills

Maintenance

Score

Reviews