The branch that would not merge

Meera starts a branch on the first of the month. She works carefully, commits often, and does not merge anything in from the main branch because she does not want to disturb what she is doing.

On the twenty-sixth she opens her pull request. It touches 94 files and conflicts with 31 of them. Two of the conflicts are in files that were restructured while she was working, so her changes no longer make sense at all.

She spends four days resolving it. Two of her fixes get lost in the process and are reported as bugs the following month.

The real problem

Not the conflicts. The time. Every day a branch lives apart, the two versions drift, and the cost of bringing them together grows faster than the work being done.

A branch that lives a day has almost no conflicts. A branch that lives a month has a week of reconciliation in it, and that week is unplanned.

What teams do instead

• Small changes. One reason for a change per branch. If the description needs the word "and", it is probably two branches.
• Merge the main branch in daily. Ten small conflicts you understand, rather than one enormous one you no longer do.
• Split refactors from behaviour. A pull request that both moves code and changes what it does is unreviewable, because the reviewer cannot tell which lines are which.

History is for the person who comes later

Commit messages are read exactly once, by somebody trying to understand why a line exists, usually at speed and usually under pressure.

fix

Reject sign-up when the email is already registered

It was silently creating a second account with the same address, so the
older one became unreachable. Found by a student who could sign in on
their phone and not their laptop.

The first tells the reader nothing. The second gives them the problem, the symptom and a way to judge whether their own change is safe.

Write the message for the person who will be reading it in a year, because that person is often you.