Git Release Skill

Use this skill when preparing releases, managing versions, and generating changelogs.

When to Use

• Preparing a new release
• Updating version numbers
• Generating changelogs
• Creating release tags
• Publishing to npm/package registries

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backwards compatible)
  │     └──────── New features (backwards compatible)
  └────────────── Breaking changes

Version Bump Rules

Pre-release Versions

1.0.0-alpha.1   # Alpha release
1.0.0-beta.1    # Beta release
1.0.0-rc.1      # Release candidate

Commit Convention

Use Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Examples

# Feature
git commit -m "feat(auth): add OAuth2 login support"

# Bug fix
git commit -m "fix(api): handle null response from payment provider"

# Breaking change
git commit -m "feat(api)!: change user endpoint response format

BREAKING CHANGE: User endpoint now returns nested profile object"

# With scope
git commit -m "fix(ui): correct button alignment on mobile"

# With body
git commit -m "refactor(database): migrate to connection pooling

- Replace individual connections with pool
- Add connection timeout handling
- Update all database queries to use pool"

Release Workflow

1. Pre-Release Checks

# Ensure clean working directory
git status

# Ensure on correct branch
git branch --show-current

# Pull latest changes
git pull origin main

# Run tests
npm test

# Run build
npm run build

# Check for vulnerabilities
npm audit

2. Version Bump

# Using npm (updates package.json and creates commit)
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0

# Pre-release versions
npm version prerelease --preid=alpha  # 1.0.0 → 1.0.1-alpha.0
npm version prerelease --preid=beta   # 1.0.0 → 1.0.1-beta.0
npm version prerelease --preid=rc     # 1.0.0 → 1.0.1-rc.0

3. Generate Changelog

# Using conventional-changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Or with standard-version (automates version + changelog)
npx standard-version
npx standard-version --release-as minor
npx standard-version --prerelease alpha

4. Create Tag and Push

# Tag is usually created by npm version or standard-version
# If manual:
git tag -a v1.2.0 -m "Release v1.2.0"

# Push with tags
git push origin main --follow-tags

5. Create GitHub Release

# Using GitHub CLI
gh release create v1.2.0 \
  --title "v1.2.0" \
  --notes-file RELEASE_NOTES.md

# With auto-generated notes
gh release create v1.2.0 --generate-notes

# Draft release for review
gh release create v1.2.0 --draft

6. Publish (if applicable)

# npm
npm publish

# npm with tag (for pre-releases)
npm publish --tag next
npm publish --tag beta

Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

## [1.2.0] - 2024-01-15

### Added
- OAuth2 login support for Google and GitHub (#123)
- Dark mode toggle in settings (#145)

### Changed
- Improved loading performance for dashboard (#156)
- Updated dependencies to latest versions

### Fixed
- Fixed button alignment on mobile devices (#167)
- Corrected timezone handling in date picker (#172)

### Security
- Updated jsonwebtoken to fix CVE-2023-XXXXX

## [1.1.0] - 2024-01-01

### Added
- Initial release with core features

GitHub Actions for Releases

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Release Checklist

Before Release

• All tests pass
• Build succeeds
• No security vulnerabilities
• Documentation updated
• CHANGELOG updated
• Version bumped

Release

• Tag created
• Pushed to remote
• GitHub release created
• Package published (if applicable)

After Release

• Verify installation works
• Announce release (if applicable)
• Monitor for issues

Hotfix Process

# Create hotfix branch from release tag
git checkout -b hotfix/1.2.1 v1.2.0

# Make fix
# ... commit changes ...
git commit -m "fix(critical): resolve payment processing error"

# Bump patch version
npm version patch

# Push and create PR to main
git push origin hotfix/1.2.1

# After merge, tag and release
git checkout main
git pull
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git push origin v1.2.1

Rollback Process

# Revert to previous version
git revert HEAD  # If single commit

# Or reset to tag
git checkout v1.1.0

# Create new patch release
npm version patch
git push origin main --follow-tags