git-workflow-and-versioning
Git conventions for trunk-based development, semantic versioning, feature flags, commit messages, and branch management. Use when making commits, managing branches, or planning releases.
SKILL.mdskills/git-workflow-and-versioning/SKILL.md
GitHubOverview
Consistent git practices make code history readable, releases predictable, and collaboration smooth. This skill covers trunk-based development, conventional commits, semantic versioning, and feature flags.
When to Use
- When making ANY git commit
- When creating branches
- When planning releases or versioning
- When deciding between feature flags and branches
Process
1. Conventional Commits
Every commit message follows this format:
<type>(<scope>): <description>
[optional body]
[optional footer]
Types:
| Type | When |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
test |
Adding or correcting tests |
refactor |
Code change that neither fixes a bug nor adds a feature |
perf |
Performance improvement |
chore |
Build, CI, dependencies, tooling |
security |
Security fix or improvement |
# Examples
feat(auth): add email verification flow
fix(api): handle null user in profile endpoint
test(auth): add registration edge case tests
security(deps): upgrade lodash to fix CVE-2024-12345
2. Trunk-Based Development
- Main branch is always deployable. Never commit broken code to main.
- Short-lived feature branches. Merge within 1-2 days. Long-lived branches diverge.
- Feature flags over long branches. For features that span multiple days:
if (featureFlags.isEnabled('new-auth-flow')) { // New implementation } else { // Current implementation }
3. Semantic Versioning
MAJOR.MINOR.PATCH
│ │ └── Bug fixes (backward compatible)
│ └──────── New features (backward compatible)
└─────────────── Breaking changes
- PATCH (1.0.0 → 1.0.1): Bug fixes, security patches
- MINOR (1.0.0 → 1.1.0): New features, new endpoints, new options
- MAJOR (1.0.0 → 2.0.0): Breaking API changes, removed features, changed behavior
4. Branch Naming
feature/short-description
fix/issue-number-description
chore/tooling-update
security/cve-fix
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'll write a good commit message later" | You won't. Write it now while the change is fresh. git commit --amend exists for minor fixes. |
| "Squash commit is fine for all these changes" | Squash when fixup commits pollute history. Don't squash when individual commits tell a meaningful story. |
| "Feature flags add complexity" | Feature flags add controlled complexity. Long-lived branches add uncontrolled complexity. Pick your poison — flags are cheaper. |
Red Flags
- Commit messages like "fix", "update", "wip", "stuff"
- Commits on main/master that break the build
- Feature branches older than 1 week without good reason
- No semantic versioning on a library/published package
Verification
- All commits follow conventional commit format
- Branch named with type prefix
- Feature flags used for multi-day features (not long-lived branches)
- Version bumped appropriately (semver) for releases
See Also
codehands:using-git-worktrees— Worktree-based branch managementcodehands:finishing-a-development-branch— Branch completion workflowcodehands:ci-cd-and-shipping— CI/CD integration with git workflow