source-control

name	source-control
description	Commit message format and release PR process. Use when ready to commit or push a release; use task-transitions for task close/review gates.
category	core
triggers	commit, git commit, commit changes, release, push release, create pr, pull request
metadata	{"gobby":{"audience":"all","format_overrides":{"autonomous":"full"}}}

Source Control - Commits, Closes, and Releases

This skill covers commit message format and the release PR process.

Use the task-transitions skill for task lifecycle transitions such as close_task, submit_for_review, validation gates, and commit SHA requirements.

---

Part 1: Commit Workflow

Step 1: Stage Changes

git add <specific-files>

Prefer staging specific files over git add -A.

Step 2: Commit with Task ID

git commit -m "[<project_name>-#<task_number>] <type>: <description>"

Use the real project name in the task reference (e.g., [gobby-#123] or [gobby-cli-#123]). project_name is a placeholder, never a literal prefix. The hyphen before # is required.

Step 3: Task Transitions (close_task, review, validation)

After committing, follow the task-transitions skill for the correct task lifecycle action (close_task, submit_for_review, review approval, validation gates, and memory review).

Commit Message Format

[<project_name>-#<task_number>] <type>: <description>

<optional body>

Valid Commit Types

Type	Use For
feat	New feature
fix	Bug fix
refactor	Code restructuring
test	Adding tests
docs	Documentation
chore	Maintenance

Examples

[gobby-#123] feat: add user authentication
[gobby-#789] fix: resolve password reset bug
[gobby-#456] refactor: extract auth logic to service
[gobby-#12] test: add unit tests for auth module

Common Mistakes

Wrong: Commit Without Task Reference

git commit -m "fix: implement feature"

Right: Include the Task in the Commit Message

git commit -m "[gobby-#42] feat: implement feature"

---

Part 2: Release PR Workflow

When you're ready to cut a release from a working branch (e.g., 0.3.1):

Step 1: Version Bump

Update all version files on the working branch:

1. pyproject.toml — version field
2. src/gobby/__init__.py — __version__ variable
3. CHANGELOG.md — add new [version] section
4. Run uv sync to update uv.lock

Commit: [gobby-#N] chore: bump version to X.Y.Z

Step 2: Push and Create PR

git push origin <branch>
gh pr create --base main --head <branch> --title "Release vX.Y.Z"

This triggers the claude-code-review.yml workflow — Claude reviews the PR automatically.

Step 3: Address Review Feedback

Fix anything flagged by the Claude review, push updates. The review re-runs on synchronize.

Step 4: Merge and Tag

# Merge the PR (via GitHub UI or CLI)
gh pr merge <number> --merge

# Tag from main
git checkout main && git pull
git tag vX.Y.Z
git push origin vX.Y.Z

The v* tag triggers the release workflow: test → build → PyPI publish → GitHub Release.

Step 5: Start Next Version

git checkout -b X.Y.(Z+1)
# Bump version files to next patch
# Commit and push

Release Checklist

• Version files updated (pyproject.toml, init.py, CHANGELOG.md, uv.lock)
• PR created to main
• Claude review passed
• PR merged
• Tag pushed (vX.Y.Z)
• Release workflow completed (check GitHub Actions)
• Next version branch created and bumped