Subversion for web development: Part 2
In part 1 of this series you learned what version control is, and how it can be useful for website development. In this second article I will give specific detail about establishing a Subversion workflow.
Structuring your repository
Before you import any data to your Subversion repository you will need some top-level directories to help organise your project. There are no set rules dictating how you approach this, but the recommended repository layout is to create trunk, branches and tags directories:
/trunk /branches /tags
Trunk: This is where you store the “main line” of development. It is a snapshot of the current state of the project.
Branches: A “branch” is a copy of the project, and allows you to carry out a separate line of development without breaking the trunk. Once you are happy with your changes they can be merged back into the main code base.
Tags: A “tag” is an archival snapshot of the project at a given point in time.
Whether or not you create branches and tags entirely depends on your own approach to version control.
Tags are commonly used in software development to capture a snapshot of a stable release of an application, but are not necessarily applicable to websites, where changes tend to be pushed live as soon as they are made.
Branching is useful when multiple developers are working on the project, but may be a redundant concept for a solo developer. Two scenarios where I can see branching would be useful are during a website redesign, or when adding a major new feature to a site. Development of the live site continues in the trunk whilst the upgrades are carried out in a branch.
Even if you don’t plan on creating branches or tags I still recommend sticking with this conventional directory naming structure. If another developer ever needs to access your repository the trunk/branches/tags structure will probably be one they are already familiar with, and it also gives you the flexibility to create branches and tags should the need ever arise.
What files to keep under version control
The only files I keep under version control are those that are required to compile and deploy the site: the source files, any files that are required on the live web server, and a copy of the site’s database.
For a typical website I create two additional folders inside the trunk:
/trunk /db /www /branches /tags
The www directory represents a web server’s public http directory. This is where most of the project files and folders live. The db directory is where I store a dump of the site’s MySQL database (more on this in part 3 of this series).
If I was working on a Flash project then I would have additional directories for my Actionscript and FLA source files:
/trunk /db /www /src /lib /branches /tags
None of these folder names are set in stone, and you should choose a structure that suits your work methodology.
Creating a working copy
To begin working with your repository you need to checkout a working copy. To do this, create a folder somewhere on your local computer, and give it a name that makes its purpose obvious. I call mine _svn_working_copy, and create it inside the job folder for the particular project it relates to. For instance, my folder might reside at D:/jobs/my_project/dev/_svn_working_copy.
Right-click on the directory you created, and choose SVN Checkout from TortoiseSVN’s context menu. In the Checkout dialog that appears, enter the URL of your repository trunk.
Once the checkout is complete your working copy should now contain the db, www, and any other directories you created in the trunk.
(You might notice that each directory in your project contains a folder named .svn. TortoiseSVN requires these folders to do its job so make sure not to delete or edit them!)
Now you can start to add files to your project, and edit them as you would usually. Remember that the www directory represents the site’s root level, so your index file should be stored here, along with any other files and folders required for the site to function.
You might be wondering “What if I need run my project in my local web server? Shouldn’t I check out the working copy to my Apache webroot?”. That’s what I initially thought too, until I realised that Apache could be configured to read files from any directory on my computer. I’ll explain how (and why) I do this in part 3 of this series.
Keeping a database under version control
If your site relies on a database then you need to keep that under version control too, otherwise you lose synchronisation if you ever need to roll back to a previous website state. But because the database is stored outside of a website’s public html directory it needs special consideration to ensure it is included with Subversion commits.
I mentioned earlier that my SVN trunk includes a directory named db. This is where I place a dump of the site’s MySQL database. In my case this is a manual process: I use PHPMyAdmin to export a .sql file which I copy into my trunk’s db directory, overwriting the previous version.
I suspect it is possible to automate the process of exporting the database from MySQL into the db folder, but for now I’m happy enough to do it manually. Like the other steps in the version control workflow it quickly becomes second nature.
When you have finished editing the files in your working copy it is time to commit them to the repository. In TortoiseSVN this is accomplished by right-clicking the folder in which your working copy resides (or any sub-folder or individual file) and choosing SVN Commit from the context menu.
At this point you have the option to add any non-versioned files to the repository, after which any new or modified files are uploaded to your Subversion server and stored in the repository. The next time anyone browses or checks out the trunk they will be able to view your changes.
Commenting your commits
It is good practice to accompany each commit with a descriptive message explaining the changes you have made. In a team environment commit log messages are a vital means of communicating with the rest of the team, but they are just as important for the solo developer. Well documented commits help you recall every change you make to your project, when you made it, and why.
Trust me, you don’t want to be the dunce, who commits with blank messages, or with meaningless ones like “Fixes”. Your team will hate you. You will hate yourself after a month, when trying to discover what the hell this code does in your brilliant project.
–Petyo Ivanov, The importance of commit messages
How often you choose to commit changes to the repository is a matter of personal preference. Once a day, twice a day, ten times a day – it’s entirely up to you.
I like to make my commits fairly frequently. This makes it easier to review the changes that I’ve made, and also keeps me focussed on the task at hand: the commit message acts as a goal for the coding session. Also, I get a small glow of satisfaction each time I make it commit, like ticking off an item on a to-do list!
In the final part in this series I will talk about working with a local Apache development server, and deploying a version controlled website to a live webserver.