| name | git-workflow-and-versioning |
| description | Branching strategy, commit discipline, PR hygiene, and semantic versioning |
| difficulty | junior |
| domains | ["general"] |
Overview
Git history is documentation. A clear commit history enables fast debugging, safe reverts, and meaningful changelogs. This skill enforces the habits that make git useful as a tool rather than just a backup system.
When to Use
- Before starting any branch
- Before committing changes
- Before creating a PR
- When tagging a release
Process
Step 1: Branch naming
Use: <type>/<description> — e.g., feat/user-search, fix/login-redirect, chore/update-deps
Types: feat, fix, docs, chore, refactor, perf, test
Step 2: Commit messages
Follow Conventional Commits:
<type>(<scope>): <description>
[optional body]
[optional footer]
Examples:
feat(auth): add OAuth2 login with Google
fix(api): handle null user_id in /profile endpoint
perf(db): add index on users.email column
Rules:
- Description is imperative mood ("add" not "added")
- Under 72 characters
- One logical change per commit
- Reference ticket:
Closes #123
Step 3: Keep PRs small
A PR should be reviewable in under 30 minutes. If it takes longer, it's too big. Split it.
- One logical change per PR
- No PRs with 500+ line diffs (with rare exceptions)
- No WIP code in a PR
Step 4: PR description
Every PR must have:
- What changed (not a list of files, but a description of the change)
- Why it changed
- How to test it
- Screenshots for UI changes
- Link to the ticket
Step 5: Semantic versioning
MAJOR.MINOR.PATCH
- MAJOR: breaking change (removing an API, changing a contract)
- MINOR: backward-compatible new feature
- PATCH: backward-compatible bug fix
Tag releases: git tag v1.2.3 -m "Release 1.2.3"
Step 6: Git hygiene
- Never force push to main/master
- Never commit secrets (use pre-commit hooks:
gitleaks, detect-secrets)
- Rebase feature branches on main before merging (or squash)
- Delete branches after merge
Verification Requirements