source-control-guidelines.markdown

Source control guidelines

Like with any writing, when using source control please show empathy for your audience. Your audience could be any one of the following people (or indeed, yourself in one of these roles):

• The Integrator. The integrator is someone preparing to deploy something. They may not need all of your changes but only a small subset. The integrator likes it when commits are small, discrete and have descriptive summaries. Commits like this make it easy for the integrator to cherry-pick commits across branches confidently.
• The New Developer. The new developer is a developer who is ramping up on a project. The New Developer sees only the end result of the technical decision-making process and lacks much of the context under which those decisions were made. The New Developer likes detailed commit messages, because they can provide details of the reasons why certain technical decisions were made alongside the codebase at a particular revision. If you've ever thought "What the hell was I thinking?" when looking at old code, the commit messages is a good place to write a note to your future self.
• The Debugger. The Debugger is a developer who is trying to figure out why a certain bit of software behaves in an unexpected way. They might be able to track the problem to a certain region of code. Version control makes it easy to see for example, a log of all commits that changed a particular file. The more information they have in the relevant commit messages, the better chance they have of intelligently fixing the problem at hand.
• The Reviewer. The Reviewer is someone who's been asked to review a particular changeset for potential problems or optimisations before merging it into another branch. The Reviewer wants to quickly figure out what the changeset introduces and examine it. They like for example, whitespace fixes to be in separate commits.

All of the recommendations in this file are there to make the life of the above people easier. If in doubt, ignore the guidelines and think about what you would rather see in any of their positions.

Here's a short list of guidelines, followed by in-depth explanations:

• Start commit summaries with a capital letter
• Make commit summaries finish the sentence "This changeset..."
• Branch names are hyphenated, lower case
• Write full commit messages (not just the summary)
• Small, discrete commits

Start commit summaries with a capital letter

• Bad: removes integration with Bananaco API
• Good: Removes integration with Bananaco API

Why?: Arbitrary. Lower or uppercase start is fine as long as we pick one and stick to it.

Make commit summaries finish the sentence "This changeset..."

Bad:

• A long time ago, in a galaxy far far away, I wrote some code and it did some things
• typo
• Oh my god why isn't this working!
• More changes

Good:

• Adds something to the SomethingController
• Removes something from the codebase
• Changes something to use the something API

Use your best judgement though. A dummy commit so you can do a Heroku deploy (e.g. after a stack upgrade) could just be Dummy commit for Heroku deploy after stack upgrade.

Why?: Makes it easier to come up a commit message summary. Also enforces that the message contains at least a description of what the contained changeset does (no meaningless "whoops!" messages).

Branch names are hyphenated, lower case

Bad:

• Banana_API_Integration
• banana_api_integration
• Banana-Api-Integration

Good:

• banana-api-integration

Why?: Arbitrary. Git supports whatever characters you like in branch names, but having them match an arbitrary standard makes them look neater together and makes them easier to guess.

Write full commit messages (not just the summary)

The summary should contain what you did. The full message should say why you did it. It should provide context, gotcha's and points to note for your future self looking back on the code in a year, scratching your head trying to figure out why you did things a certain way.

Bad:

Makes us floob the barflab

Good:

Makes us floob the barflab

Until now we've been processing payments using the XYZ API
synchronously. To make the system less error prone (and 
allow us to re-attempt failed payments) this changeset moves 
payment processing into a background job using foo (backed with 
bar).

As per the XYZ documentation[0], we won't be able to use XYZ in
ABC mode. @fred and I decided that this was acceptable.

[0]: http://example.com

Why?: Even small code changes can have a lot of thinking in the decision-making process. By writing a detailed commit message, you give future developers an insight into why you made a certain change so they don't have to guess at your intentions. In-depth commit messages can also help them avoid re-introducing problems that you were trying to fix.

Small, discrete commits

It's difficult to define exactly what we mean here by "discrete" commits so you'll need to use your own discretion (literally, hahah!). As a placeholder, let's say a "discrete commit" is a commit that introduces a single small change that can be easily described in the commit summary.

Your commits are probably not discrete if:

• You have to use the word "and" in the commit summary
• You could imagine wanting to merge only one part of the commit into another branch
• It contains meaningful code changes alongside whitespace fixes.

Why?: During integration it's much easier to confidently cherry-pick changes across branches if each commit introduces one small change that can be easily described in the summary. Also, small commits can have their changes aggregated using commit ranges between refs. Separating out changes large commits on the other hand isn't easily done using version control.

Avoid the -m on your git commit at all costs

-Miguel Grazziotin

That will always compels you to write a quick commit message instead of detailing the reason of that change.