Every team has a Git workflow, but most teams keep it in their heads. A new developer then learns it by breaking it: committing to the wrong branch, force-pushing the wrong thing, opening a 2,000-line PR on day three. A one-page written workflow and a little automation fix most of this before it happens.
Write down the five decisions#
However your team works, these five choices define it. Put them in the README or CONTRIBUTING.md:
- Where work happens: feature branches off
main, or straight to main for tiny teams. - How branches are named:
feature/short-name,fix/thing, whatever - consistency matters more than the scheme. - What a pull request needs: description, linked ticket, one approval, green CI.
- How merges land: merge commit, squash, or rebase - Merging vs Rebasing for Small Teams if this is still unsettled.
- How releases happen: tags, changelogs, deploy steps. Tagging Releases Properly covers the shape.
A new hire who can read those five lines commits correctly on day one.
Automate what is enforceable#
Rules that live only in the document decay. The ones that survive are enforced by the repo itself:
- Branch protection on main, so “don’t push to main” is a fact, not a preference.
- Git hooks for the local checks - Pint, tests, no debugging leftovers.
- Conventional commits if the team wants parseable history, with a commit-msg hook to back it.
Automation also shortens the document: you stop writing rules down once the tooling states them for you.
Pair on the first pull request#
The highest-leverage onboarding hour is walking a new developer through their first PR the team’s way: small branch, tidy commits, a description a stranger could review from, responding to comments without defensiveness. Point them at the team’s own posts on small pull requests and PR descriptions if you have them - or write yours down once and link it forever.
The measure of a good onboarding is how boring the second week is: the new hire ships a small PR, gets one round of comments, merges, and nobody had to correct a Git habit. That outcome is designed, not lucky.
Share this post
Keep reading
A First CI Pipeline for a Laravel Project
Install, lint, test, build - four jobs that run on every pull request and turn 'works on my machine' into a check everyone can see.
A Staging Environment Worth Having
Staging only catches what it shares with production. Same deploy path, same services, sanitized data - and a clear rule for what it is for.
Branch Naming Conventions That Scale Past Three People
Branch names are a user interface for your team's work. The conventions that survive growth, the ones that collapse, and why boring always wins.
