SCM at a small software shop

I am not going to bore you with the details of using git. There are plenty of amazing resources out there, but I can recommend some reading though:

What we are going to discuss in this guide is very simple: How to prevent (most) conflicts.


The reason we use git is very simple: It is very powerful. It allows us to have a complete copy of our repository in our machines. That’s YOUR copy. That’s the complete history and as developers, history is our friend. Other systems such as SVN, CVS or TFS rely just on the snapshot of a specific version (usually the latest) stored in a central repository. Which is cool, but not the best that we can do. There is a fundamental problem with this approach:

There’s no baseline!

What do I mean by baseline? A baseline is simply a known version of the code to work on. A version that everyone can always go back to and know which features are working and identify specific bugs. And knowing where you stand is good.

wile e coyote defies the baseline

I usually follow SemVer so each release has an associated v.Major.Minor.Patch version. The baseline is usually the most recent one. The team always builds upon this version. Please note that I used the term usually because of course there are cases where team members are working on related issues and these team members will likely affect the same resources leading to conflicts (both human and in source code) but timely communication between team members helps much more than tools.

With this background, we can now establish some rules:

  1. Always base your changes on a known baseline, preferably the latest tag.

  2. Commit often, I beseech you to leave behind your habits of commenting out code and modifying the code “to see if it works”.

  3. Backup your work. (AKA git push)

You might now be wondering, git push? But git will force me to pull first ಠ_ಠ

And you are right. And that’s why we have this guide.

The actual process

  1. Fork the repo in{canonical_account}/{repository-name}

  2. git clone{your_username}/{repository-name}

  3. You’ll see that we usually have master and develop branches. This is because we follow git flow.

  4. When starting to work on a new issue, I recommend you to do a git checkout -b issue/zzzz v.X.X.X where v.X.X.X is the baseline and zzzz is the number of the issue you’ll be working on.

  5. You should commit as often as you desire. I discourage you from doing “Fixes #zzz” on every commit though, because it is very confusing to see several of those comments in the history. You can either rebase and squash your changes or just do a simple git commit --ammend when you see your changes are not really working yet.

  6. When you are done with your changes, you can simply send a pull request against the develop branch. This delta of changes will usually contain only the modifications related to that specific issue, making it easier to control which changes we’re pushing to our staging, and subsequently, production environments.

If you noticed, in no moment of this guide we’re pulling from the remote. The reason is because you are working on a known state, in this case v.X.X.X i.e. we’re effectively restricting who advances develop and master.

What if I need to coordinate certain changes with another(s) team member(s)?

Very simple: You just do this very same process in a smaller scale. Just create a branch on either your fork or one of your teammates’ fork and share commits accordingly. This is that case where the baseline is not the tagged baseline, but an intermediate branch agreed by the participants. When you guys are done with your respective changes, just generate an appropriate pull request to develop on the canonical repository. Because you both share commits, and you solved the conflict contextually, the resulting merge (if any) is waaaay easier.