Git Workflow

Git Workflow

Branching, commit, and PR conventions for this project.

Branch Naming

feat/<short-slug>        # new feature
fix/<short-slug>         # bug fix
chore/<short-slug>       # tooling, deps, config
infra/<short-slug>       # server/infrastructure changes
hotfix/<short-slug>      # urgent production fix

Examples:

• feat/client-dashboard
• fix/nginx-ssl-renewal
• infra/promtail-php-logs

Commit Messages

Follow Conventional Commits strictly:

<type>(<scope>): <short description>

[optional body — what and why, not how]

[optional footer — breaking changes, issue refs]

Types: feat, fix, chore, refactor, docs, test, infra, perf

Rules:

• Subject line: imperative mood, lowercase, no period, max 72 chars
• Body: wrap at 72 chars, explain why not what
• Never: "WIP", "fix", "update", "misc", "changes"

Good examples:

feat(auth): add per-client JWT validation

fix(nginx): prevent vhost config clobbering on panel reload

infra(promtail): add php-fpm log scrape target

Workflow

main              # production — protected, no direct push
  └── feat/x      # feature branch — PR required to merge
  └── fix/y       # fix branch — PR required to merge
  └── hotfix/z    # merge to main + tag immediately

1. Branch from main
2. Commit with conventional commits
3. Run /review before opening PR
4. Squash merge into main — keep history clean
5. Delete branch after merge
6. Tag releases: v<major>.<minor>.<patch>

Before Every Commit

git diff --staged          # review what you're committing
nginx -t                   # if nginx configs changed
git status                 # ensure no unintended files staged

Useful Aliases

Add to .gitconfig:

[alias]
  lg = log --oneline --graph --decorate --all
  st = status -sb
  unstage = reset HEAD --
  last = log -1 HEAD --stat

Common Mistakes

Committing directly to main — main is protected. Always branch, even for a one-line fix. Hotfixes go through hotfix/<slug>, not directly.

Vague commit messages — fix, update, wip, misc are not commit messages. They tell you nothing in git log. Use conventional commits with a scope and a description that explains what changed and why.

Forgetting to squash merge — merge commits pollute the history. Squash merge feature branches into main to keep history linear and readable.

Long-lived branches — the longer a branch lives, the worse the merge conflict. Branches should live hours to days, not weeks. If it's taking weeks, the task wasn't broken down small enough.

Committing generated or config files — config/, .env, and build artifacts should not be committed. Check .gitignore before the first commit on any new project.

Tagging without purpose — tags are for releases (v1.2.3), not for bookmarks. Don't tag intermediate states.