Developers Die. Projects Must Live On. (Intro + Version Control)

I'm the only front end engineer on my team and like most of us, I've got a crushing feature backlog.

Earlier this year I had the realization that if I left the project, it would either die or be completely re-written by the next guy. It wouldn't suffer this fate because I've written bad code, but because I'd been using the large feature backlog as an excuse to neglect all of the non-code parts of the project that enable developers to be effective.

The project in question is an application I helped conceive and something that has the potential to make the lives of our internal business customers much easier. Needless to say, I've got an emotional attachment to it and want to see it survive whether I'm working on it or not.

So, I set out to fix the situation. I did some research to try and figure out what best practices and tools I could use. After some time I was able to put together a list of things I needed to do in order to harden my project against turnover (or make on-boarding new teammates much easier).

Disclaimer

These articles are written to serve as a jumping off point for someone in a similar situation. They are intended as an entry level discussion. I give some tips on how I implemented the discussed concepts as I produced features, but those who are an on a mature team probably won't gain much from this series.

The List

Git the most out of version control (see what I did there?)

More better documentation

Implement a coding style guide

Easily reproducible environments

Testing...ugh

Utilize build tools

Setup continuous integration

Version Control

“Any kind of practice that tracks and provides control over changes to source code” - Wikipedia

Most of us use or have at least heard of version control before. But for those that are new to the subject, its just a system of keeping track of the changes you've made to your code.

Version Control Systems

Software that helps track these changes are called Version Control Systems (VCS).

There are 3 major VCSs to be aware of. They share many of the same major features but have some significant implementation differences. I encourage you to try them all out and choose one that fits your way of thinking and meets your needs.

Git

Mercurial

Team Foundation Server VCS

Git

Git is currently the most popular of the 3 due largely to its widespread adoption in the open source world. Most open source tooling around VCSs assumes that you're using Git. It has been described as the "MacGyver" of VCSs because it has lots of utility functions and there seem to be multiple ways of accomplishing the same thing.

Mercurial

Mercurial debuted around the same time as Git in 2005. It was a strong competitor to Git until around 2010 when Git seemed to gain critical mass. It has been described as the "James Bond" of VCSs because many people believe usage of it to be more elegant than Git.

The main online repository service that supports Mercurial is Bitbucket.

Team Foundation Server VCS

This is Microsoft's VCS. If your company is mainly a Microsoft shop, there's a good likelihood that you'll want to use TFS as it integrates nicely with all of the Visual Studio environments and tooling.

My favorite is SourceTree because I can use it for my Git and Mercurial projects, but you should check them all out and choose the one that best fits you and your needs.

Issue Tracking

Many of the VCS services provide a way for developers and users to submit issues and discuss them. I won't get into issue tracking much here besides to say that many developers, even solo developers, find issue tracking to be a fantastic way of keeping track of required maintenance for their applications.

Commit Messages

Once you're using version control, one of the most important things you can do to help your team understand the changes happening on the project is to write good commit messages.

Good commit messages describe 3 things.

The issue being fixed or feature being added

The changes made and the rationale behind them

Any side-effects the changes bring

Examples

Bad Commit Message

commit -m "Fixed a spinner bug."

Notice 2 things here.

Firstly, the message is incredibly vague. What spinner bug? Where is it? How'd you fix it?

Secondly, its written in the command line. Executing VCS commands from the command line is not necessarily a bad thing, however, committing from the command line makes it very hard to craft good messages.

Good Commit Message

From a VCS tool

Stops the spinner from showing on form A's "ok" button hover (#123)
Removes the event trigger that caused the spinner to show when the user hovers over the "ok" button.

As you can see, this message was written in a VCS tool. This allows you to format the message in a way that's conducive to writing good, informative commit messages. Some of the tools even allow you to write commit messages in markdown. Fancy!

You'll also notice how specific the first line is. It explains the issue being addressed and also where in the application you'd find the issue (Form A's "ok" button). It even has a reference to an issue number (the VCS you use may have a more integrated way of linking commits with issues).

The second paragraph explains what was done to address the issue. This is where you can get a bit more technical and where you'd go into rationale if necessary.

Branching

Branching is a feature of VCSs that allows you to make as many changes to your code as you want while still maintaining a version that is ready for your users. When you're done making changes, the VCS will assist you in "merging" all of your changes back into the main version.

The Theory

In this example there is a main development branch. A branch for Feature A is started, but before it is finished Feature B is started in its own branch. Likewise, before Feature B is finished, Feature C is started in its own branch. After that Feature B is finished and merged back into the main development branch, then Feature C, then finally Feature A.

The theory here is that at any point in developing Feature's A, B, or C the main development line could be put into production.

My Branching Scheme

The branching scheme I use is based off of a Mercurial plugin called Hg Flow which is also a built in feature in SourceTree. There exists a "Git Flow" as well, but I have little experience with it.

It looks a little something like this:

The heart of the repo is the development branch. It is the branch from which features are started and the branch that completed features join the herd. When a substantial feature set is finished, the development branch merges into the production branch.

Hg Flow and Git Flow have convenience functions to facilitate this including a "Start Feature" button that opens a new branch and even namespaces the feature with "feature/".

Conclusion

Version control is the most basic, yet most powerful thing you can do to start working in a team-friendly environment. Its easy to take shortcuts in branching workflow and in writing commit messages, and we all do it from time to time. However, creating and following VCS guidelines will enable your team and save you from unexpected headaches.