home / skills / serejaris / ris-claude-code / git-workflow-manager

git-workflow-manager skill

safe

This skill enforces conventional commits, semantic versioning, and changelog discipline to streamline releases and improve project clarity.

npx playbooks add skill serejaris/ris-claude-code --skill git-workflow-manager

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

3.0 KB

---
name: git-workflow-manager
description: Use when committing, releasing, or managing changelogs - enforces conventional commits, semantic versioning, and consistent release notes format
---

# Git Workflow Manager

## Overview

Enforces consistent git workflows: conventional commits, semantic versioning, changelog updates, and release notes format.

## Commit Convention

```
<type>: <description>
```

| Type | Description | Version Bump |
|------|-------------|--------------|
| `feat` | New feature | MINOR |
| `fix` | Bug fix | PATCH |
| `docs` | Documentation | — |
| `refactor` | Code change | — |
| `chore` | Maintenance | — |

Breaking change: `feat!:` or `fix!:` → MAJOR

## Version Bump Rules

```
Current: 1.2.3

feat:     → 1.3.0 (MINOR)
fix:      → 1.2.4 (PATCH)
feat!:    → 2.0.0 (MAJOR)
docs:     → no bump
```

## Workflow: Commit

```bash
# 1. Stage changes
git add .

# 2. Commit with conventional message
git commit -m "feat: add new feature"

# 3. For multi-line:
git commit -m "$(cat <<'EOF'
feat: add feature

Detailed description here.
EOF
)"
```

## Workflow: Release

```bash
# 1. Determine version bump from commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# 2. Update CHANGELOG.md
# - Move [Unreleased] items to new version section
# - Add date: [1.3.0] - YYYY-MM-DD

# 3. Commit changelog
git add CHANGELOG.md
git commit -m "docs: update changelog for v1.3.0"

# 4. Create tag
git tag -a v1.3.0 -m "Release v1.3.0"

# 5. Push
git push && git push --tags

# 6. Create GitHub release
gh release create v1.3.0 \
  --title "v1.3.0 — Short Description" \
  --notes-file /tmp/release-notes.md
```

## Release Notes Template

```markdown
## What's New

### Feature Name
Brief description.

**Key points:**
- Point 1
- Point 2

### Installation (if applicable)
\`\`\`bash
command here
\`\`\`

---

**Full Changelog**: https://github.com/USER/REPO/compare/vPREV...vNEW
```

## CHANGELOG.md Format

```markdown
# Changelog

## [Unreleased]

## [1.3.0] - 2025-12-17
### Added
- Feature description

### Changed
- Change description

### Fixed
- Fix description

[Unreleased]: https://github.com/.../compare/v1.3.0...HEAD
[1.3.0]: https://github.com/.../compare/v1.2.0...v1.3.0
```

Sections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`

## Quick Commands

| Task | Command |
|------|---------|
| Last tag | `git describe --tags --abbrev=0` |
| Commits since tag | `git log $(git describe --tags --abbrev=0)..HEAD --oneline` |
| Create release | `gh release create vX.Y.Z --title "vX.Y.Z — Title"` |
| Edit release | `gh release edit vX.Y.Z --title "New Title" --notes "..."` |
| List releases | `gh release list` |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| No conventional prefix | Always use `feat:`, `fix:`, etc. |
| Forgot CHANGELOG | Update before tagging |
| Tag without release | Always `gh release create` after tag |
| Inconsistent title | Format: `vX.Y.Z — Short Description` |
| Missing comparison link | Add `**Full Changelog**: compare/...` |

Overview

This skill enforces a consistent git workflow for commits, versioning, changelogs, and release notes. It automates and validates conventional commit messages and maps them to semantic version bumps. It also standardizes changelog structure and a release notes template to keep releases predictable and traceable.

How this skill works

It inspects commit messages since the last tag to determine the required semantic version bump (major, minor, patch) based on conventional commit types and breaking-change markers. It guides updating CHANGELOG.md by moving Unreleased entries into a dated release section and commits those changes, creates an annotated tag, and helps publish a GitHub release with a formatted release notes file. It provides quick commands and templates to avoid common mistakes and maintain a uniform release process.

When to use it

Before committing code to enforce conventional commit messages
When preparing a release to compute the next semantic version
When updating or generating CHANGELOG.md entries
When creating a GitHub release to ensure release notes follow a template
During CI checks to validate commit and changelog consistency

Best practices

Always prefix commit messages with conventional types (feat:, fix:, docs:, refactor:, chore:)
Use feat!: or fix!: to indicate breaking changes and trigger a major bump
Update CHANGELOG.md from the Unreleased section before tagging
Commit the changelog change separately using docs: update changelog for vX.Y.Z
Use annotated tags (git tag -a) and create a matching GitHub release with gh release create

Example use cases

Compute next version from commits since last tag and choose correct bump (patch/minor/major)
Move Unreleased changelog items into a new dated section and commit the update
Create an annotated tag and push tags, then publish a GitHub release with a prepared release-notes file
Run a pre-release script in CI to fail the pipeline on malformed conventional commits
Generate release notes from structured sections (What’s New, Key points, Installation) for consistent user-facing releases

FAQ

How does the skill determine a major version bump?

A major bump occurs when a commit includes a breaking-change marker like feat!: or fix!: or when commit body indicates BREAKING CHANGE. The tool scans commit headers and bodies since the last tag.

What sections should CHANGELOG.md include?

Keep these sections: Added, Changed, Deprecated, Removed, Fixed, Security, plus an Unreleased section and per-version dated sections for released versions.