A series on best practices in large codebases for new engineers. This one focuses on version control etiquette.
If you’re new to using git on a team instead of solo, this super fast primer will help you get started with standard workflows and etiquette.
Hopefully not what your commit history looks like! By austrini [CC BY 2.0 (http://creativecommons.org/licenses/by/2.0)], via Wikimedia Commons
Use feature branches
Use feature branches. Don’t push your work directly to the master branch until it’s finalized and (depending on your team’s culture) code reviewed. This is basic and discussed in many great tutorials so I won’t go into detail, but it’s a precursor to pretty much all work in larger teams.
Don’t mix bug fixes with feature work
If there’s a bug in the master branch, it’s a good idea to create a new branch (perhaps with a name starting with “fix/”) and file a pull request. An independent branch ensures that the fix can be merged independently of other work. If you tack it on to a pull request for a less important feature you might hold up others who are waiting for the fix and create many angry team members.
Write clear commit messages
When you’re working on a team, the repo’s commit history is a vital record of the progress of a project and an essential tool for finding bugs and understanding code. In three weeks or three years, somebody (even you!) might look back at your commit message to figure out why you wrote something. Help them out! Try to make your commit messages as clear and concise as possible.
Not clear:
“Fix bug with colors”
Clear:
“Fix issue #16: make send button change colors on press”
Not very specific:
“Add list endpoint”
Specifies the relevant part of the repo:
“[Photos controller] Add functionality to list recent photos”
Squash commits before merging
Squashing commits is the process of taking several commits and rewriting them into one commit. Squashing creates a clean commit history. When you and your teammates are looking back at the log on master, instead of seeing a jumble of crap like this:
Thu May 18 13:52 lint errors
Mon May 22 14:47 Feedback from CR
Thu May 18 16:04 Lololol oops
Thu May 18 16:03 Fix tests
Thu May 18 13:52 Fix lint errors
Thu May 18 13:39 Forgot to add file
Thu May 18 13:36 Start on compression
They’ll only see one commit with a clear description of your change:
Mon May 22 15:47 Add video compression option to uploader
Squashing means you can feel free to have lots of crazy work-in-progress commits on your feature branch. Just clean it up with a squash before submitting your pull request and/or before merging with master.
There are several ways to squash with git. GitHub actually now allows you to squash commits with the GitHub UI. If your repo has the correct settings turned on you’ll see a “squash and merge” button on your pull request.
Rebase before merging
Consider rebasing your branch on top of master before you merge. If you merge, you’re combining master and your branch by creating a new commit that corrects conflicts:
[on master] Merge branch ‘video_compression’
[from your branch, now on master] Add video compression option to uploader
[from master] Fix issue #17: remove uploader exit button
You could end up with a lot of merge commits this way. If instead you rebase on top of master, you correct the merge conflicts in your commit and end up with this cleaner history once you merge:
[from your branch, now on master] Add video compression option to uploader
[from master] Fix issue #17: remove uploader exit button
One warning: it’s always better to squash THEN rebase instead of rebase then squash. Git rebases commits one by one. If you haven’t squashed, you’ll need to resolve conflicts in every commit it in your branch with master. If you squash, you’ll only need to resolve one commit’s conflicts.
And that’s it!
Keep in mind that these tips all describe fairly common practices, but customs vary from team to team. If you’re working on a codebase with an existing repo, ask your teammates about their git conventions.
If you have any other tips for gitting on a team, feel free to leave them in a response.
Article 1: Trust No One: An Introduction to Large Codebases for New Engineers
Article 2: A Beginner’s Guide to Automated Testing
Article 3: Quick Tips for Gitting on a Team