Submitting to Subversion

This is the first in a four-part series about how Brettro integrated Subversion into its workflow. Part two will discuss the products Brettro uses to manage its SVN repositories, part three will discuss how Brettro uses SVN with ExpressionEngine and part four will talk about how Brettro uses SVN with WordPress.

About a year ago I tackled the task of integrating version control into my coding practices. I had spent a frustrating amount of time either recreating my code base as I started on new projects or backtracking and rewriting code when I would get a flash of inspiration to try something new. Also, I have both an iMac and a MacBook Pro and I use them interchangeably and wanted to be able to have the most up-to-date code on both of machine. Plus, it seemed all the pros were doing it—and since I consider myself one—I should join the gang.

Why Subversion?

Usually I do quite a bit of research, compare features and discover the value of one product over another. In choosing SVN, however, all I knew was that the WordPress Core Team used it. That, in and of itself, was a strong enough testimonial for me to dive right in.

Getting Started

When I know nothing about a topic, I buy a book, which is the first thing I did. I picked up Apress’s Practical Subversion, second edition, plopped down and started reading. I read chapters one, two and six completely as they provided an overview of version control in general, a “crash course” in Subversion and best practices in using Subversion. (By the way, Subversion is also known as SVN.)

Although clearly and plainly written, I was still confused as to the best way to get started and the best way to integrate SVN into my current workflow. I asked folks how they used it. I tweeted about my confusion consistently. I read blog entries and articles ad nauseum. I definitely hadn’t had my “ah ha!” moment yet.

Integrating SVN into My Workflow

As it turns out and after some starts, stops and stumbles, I realized that my current workflow wasn’t so much a “workflow” as much as it was a “jumble-of-tasks-that-stumbled-over-themselves” to get a project done. So I began to map out two workflows: one for managing Brettro web properties and one for creating and managing client web properties. This was really helpful as it:

• Clarified the basic SVN concepts of trunks, tags and branches, and
• Formalized how I create, produce and maintain website code.

Creating a Foundation: My HTML ‘Codebase’

With a better understanding of the basic SVN terminology and process, I decided to start with a fresh series of HTML, CSS and JavaScript files that would serve as the basis of all my website code from hereon out; and I’d call it my “codebase.” This seemed to be a great time to:

• Make the switch from HTML 4/XHTML 1.1 to HTML5,
• Adopt HTML5Boilerplate, a well-maintained framework established to ensure HTML5 code worked fairly well on legacy browsers (like any version of Internet Explorer before IE9),
• Adopt 960.gs, another well-maintained framework established to ensure CSS consistency across browsers, and
• Create the Brettro website design style manual.

Repositories, Trunks, Branches, Tags and Working Copies

Let’s get some basic terminology out of the way:

• Repository: the “repository” (or “repo”) is the container where your SVN-managed code is kept;
• Trunk: the “trunk” is the main codebase of a project where most of your development will occur;
• Branch: a “branch” is an offshoot of the trunk (do you see the tree metaphor?) whereby you might want to try out an idea or a feature that may not actually make it into production;
• Tag: a “tag” is a copy of either the trunk or a branch frozen at a specific point in time, such as a release (the tree metaphor comes to a screeching halt here); a tag is never modified once it’s created;
• Working Copy: the “working copy” is either the trunk or a branch copied to your computer from the repo to allow you to make changes.

After all this reading, contemplating, starting, stopping, deleting and creating, I settled on a basic structure that works for me. I’d like to think it’s a pretty common structure because it is based on my understanding of how WordPress organizes their SVN repository (and I like to use best practices because there’s no need to reinvent the wheel):

Trunk

This is where I do my “next major version” development. For example, right after I finished my HTML5 codebase, HTML5Boilerplate released version 2 of their product. Rather than integrate those changes into version 1 of my codebase, I’ll integrate them into version 2 and do that development here.

Branches

When I imported my initial HTML5 codebase into my first SVN repo, I immediately created a branch and named it “1.0.” The “1.0” branch is my working copy of my HTML5 codebase code where I squash bugs and make minor fixes, then release them as dot releases. These releases are merged back down to the trunk so that they are included in the next major version codebase release.

Tags

After creating my “1.0” branch, I also created a “1.0” tag. This gives me a complete capture of version 1 of my HTML5 codebase so that I have a stable, working copy to use to create new projects.

Committing to SVN (See what I did there?)

By finally having an understanding of basic SVN techniques, by documenting my SVN structure and practices and by creating my first version controlled codebase, I was ready to take a deeper dive. Next I created branches of my codebase for both my WordPress codebase and my ExpressionEngine codebase. Stay tuned to the next three parts to learn what software I use and what workflow I use to manage sites built with either of these content management systems.