A Primer on Source Control

Source code control is nothing new to software development. It’s been around for decades. But for those of us who work in the open source community, specifically those who are working with WordPress, we may not have the experience that some of our peers have.

After all, many of the people who work on or work with WordPress are people who are seasoned software developers or who have been working on software for a long time.

A Primer on Source Control: A plugin's repository.

The online Subversion repository for a simple WordPress plugin.

And to be clear, this doesn’t mean they learned source control within the context of open source development – maybe they did, maybe they didn’t. In short, they’ve had time to learn the advantages of workflows for and reasons why source control is so important.

Ultimately, the point I’m trying to make is this:

If you’re new to WordPress, and you’ve heard about source control, Subversion, Git, or GitHub or even used it to some degree (even if you aren’t entirely sure what you’re doing), that’s okay! Everyone starts at the beginning.

The purpose of this primer is to help explain some of the benefits of source control, why we use it, and how it plays a role in our day-to-day activities especially when we’re working with others.

A Word About WP Pusher

If you’re reading this, there’s a significant chance that you’re doing so because you’re aware of Peter’s project, WP Pusher. It’s a fantastic piece of software that makes it easy to deploy your code from a source code repository.

A Primer on Source Control: WP Pusher

Of course, that’s predicated on the idea that you know how to commit your code to a source code repository.

The whole idea behind WP Pusher is simple:

Take the pain out of WordPress development. Deploy directly from GitHub or Bitbucket and never again copy files over FTP. It works everywhere – even on cheap shared hosting!

And it sounds great, doesn’t it? One less step to deploying our source code to a staging environment or a production environment or any other generic server right from within WordPress itself.

Let’s take a step back, though, and talk a bit about the purpose of source control.

A Short Primer on Source Control

Source control (also referred to as source code control or version control) has been around for a long time. In short, it’s meant to make it easy to take snapshots of your code at various intervals of development.

Wikipedia defines it as:

A component of software configuration management, version control, also known as revision control or source control, is the management of changes to documents, computer programs, large web sites, and other collections of information.

Not bad, but what does this mean for us?

In short, this means if you introduce a bug in one commit, you can rollback to a previous commit where the bug didn’t exist.

Sounds great, right? It’s kind of like rewinding time (or rewinding development time, at least). But it gets a little more complicated from there.

We’ll look at a scenario in how working with source control plays out a bit later in this article, but there are a few things that I think every developer should understand when they first get started working with source control.

More Than a Backup

Source control is not necessarily a backup of your project. Sure, your code is being stored in an offsite location so if your local machine were to die completely, your code would be safe.

But we have backup solutions (like external hard drives and cloud services) for a reason.

To that end, don’t think of source control as a place to where you’re sending your source code to be safe should something happen on your machine.

It’s much more than that.

Your Code Throughout Time

We’re all familiar with software versions. That is, we’re familiar with version 1.0 of a product (or maybe they use a different versioning scheme like Windows 95 and Windows 98 or OS X Leopard and OS X Snow Leopard).

Whatever the case, software goes through versions and each version usually includes bug features, feature improvements, or a combination of the two.

And this is where source control comes into the picture.

As we’re working on a project – no matter how big or how small – we are making incremental changes with each line of code we write. And with each line of code, we’re changing the state of the software. This may be for fixing bugs, this may be introducing a new system, or this may be inadvertently adding a bug or breaking something.

But if you’re committing frequent changes to your repository, you’ll be able to rollback easily to the last version that worked and start again from that point.

A Primer on Source Control: Code Through Time

Various commits of code from a project (or code throughout time).

On the other hand, let’s say that your code has gotten to a point where it’s extremely stable, and it’s ready to be released to the public. In this case, you can stamp it with a version and then ship the code at that point in time.

This gives to a milestone from which you can begin to continue working on the project, and you will start a new round of improvements on the codebase.

What About This Branching Thing?

One of the things that cause new developers to trip (or at least those who are new to source control) is the idea of branches.

Different source control systems, be it Subversion, Git, Mercurial, or what have you, will call them different things. But the idea behind the terminology is the same.

For any given project, there is a main line of development. Sometimes this is called the trunk, sometimes this is called the master branch. What it’s called doesn’t matter so much as how it’s treated.

The mainline of development should be where all of the stable code is merged whenever it’s ready to be shipped. This means that whenever you, a peer, or anyone else checks out a project to work on it, they should create their branch.

A Primer on Source Control: Branching with a Team Member

An example of a project where a friend branched from my code.

This ensures that whatever it is they are working on will be done so within the context of their development environment. Furthermore, it ensures their code will not be overwritten or will conflict with anyone else’s code.

There are still opportunities for this to happen, but we’ll look at that momentarily.

Instead, you should work on your branch of the code just as you would if you were working on the main line of development. That is, write code to make an incremental change, commit it to the branch, and then repeat.

Once you’ve completed all of your work, it’stime to merge it into the master branch. And this is where things can get a little more complicated

Merge Conflicts? (I Don’t Like Conflict)

No one likes conflict, and when it comes to source code control, it’s an inevitable truth that you will experience it.

A merge conflict is when there have been changes to an area of the code where at least two developers have made changes, and the version control software can’t figure out how to merge the changes.

Thus, it’s up to you, your peer, or both of you working together. Luckily, there is software that makes this much easier. For example, the software will often show the source code in two separate panes, and then it will allow you, for each part of the conflict, which line of code you want to merge into the new file.

A Primer on Source Control: Merge Conflicts

Kaleidoscope is one such application for managing merge conflicts.

Once done, the file you’ve created during the merge conflict resolution is what you will commit to the main line of development.

This doesn’t sound that hard, but it depends on your workflow. If you’re making incremental changes and you’re committing code in small batches, you’re going to have a much easier time to handle merge conflict.

When possible, avoid doing any “big bang” merges or “big bang” releases. It’s better to take a more fine-tuned approach especially when you have multiple people and multiple branches on a project.

So What Now?

The purpose of this post was to give a primer on some of what you can expect when working with source control. To summarize this, I’d say the most important points are:

  1. Don’t treat source code repositories as a backup,
  2. Branch from the mainline of development as soon as you’re ready to begin work,
  3. Make frequent commits,
  4. Don’t resolve merge conflicts alone.

For my day-to-day, I work on a Mac so I partial to using Tower. I also tend to use GitHub since I primarily work in open source software and am a fan of how they offer wikis, issues, milestones, and more.

With that said, there are also alternatives such as Versions, Subversion, Cornerstone, Bitbucket, and more.

And if you’re on Unix or Windows, feel free to share your own favorite software in the comments!

Back To WP Pusher

Finally, if you have any experience with working with source code control, then you know it can be quite tedious to commit the code, tag the version, export the code, connect to the server via FTP, and upload the code.

To cut out all of those steps, WP Pusher allows you to push directly to your server of choice from your Git-based repository. It takes several steps out of the deployment process saving you lots of development time.

So between a better understanding of version control and knowing just how much time can be saved using a utility like WP Pusher, perhaps you’re ready to move your WordPress development a little bit further along than it was before this post.

This primer on version control was contributed by Tom McFarlin. Tom is the founder of Pressware and recently launched “Start Here“, a closed and limited membership site for aspiring WordPress developers.