This article is the third in a series of guides about my experiences using Subversion (svn) for Web Development. These are the articles in the series:
1. A Desktop-Laptop Solution for Web Developers – Using Subversion to Co-Exist (this article)
2. What is Subversion and How Does it Help in the Web Design and Development Process?
3. A Subversion Workflow for Web Developers and Web Development (this article)
4. A Review of SmartSVN – a GUI Subversion client for Windows
5. A Quick Review of Online Options for Hosted Subversion for Web Developers
6. A Brief Review of Assemmbla, an Online Subversion Hosting Company.
Now that you understand a little bit about my rational for using subversion and the very basic concepts for using SVN, let’s take a look at my own web development workflow using Subversion (and Dreamweaver).
I. BASIC SETUP AND CONFIGURATION
A. Setup the client directory on the local or development machine: I keep all of my client files in one folder. So client_1 has a folder /client_1 where all of client_1’s files are kept. Among the other folders in the /client_1 directory are two web specific folders: the /client_1/web directory contains the main website files, usually in /web and the /client_1 /webBackup directory has the backups. These backups are either release versions or increments in the development process. Whereas in my older workflow I referred to the iterations as simply “web backups”, now that Im using subversion nomenclature I call these iterations tags. The image below shows the contents of a sample /client_1 directory:
B. Setup a Subversion repository. If you are new to SVN you can head to one of the Subversion Hosting Companies listed in Part 6 of this series (coming soon), and explore them for yourself to see which company meets your needs. Many of these companies have trial periods and/or free accounts. You can also setup your own SVN repository on a VPS or dedicated server, but if you’re new to SVN I’d recommend you start with a hosted service to make sure using SVN works for you in your web development cycle.
C. Install a SVN Client such as Tortoise SVN or SmartSVN. I actually use Tortoise SVN and SmartSVN on different machines. They are both excellent programs for helping you interface with your SVN repository. SmartSVN is a GUI client so as someone who was completely new to SVN, I found it easy to work with. You can read my review of SmartSVN in article #4 of this series (coming soon).
D. Setup Dreamweaver as you normally would for a website (“Manage Sites”). While Dreamweaver does have some checkin/checkout features and there are plugins for SVN, I’m not using these options. In my workflow I’m developing completely in Dreamweaver, and DW doesn’t know about SVN. There may be better ways to do this but right now this workflow works for me. Note also that I’m using Dreamweaver CS3, as I’m still quite happy with the programs features and how it performs.
II. SUBVERSION WORKFLOW FOR WEB DEVELOPMENT AND DREAMWEAVER
A. Get the local /web folder talking to the /trunk folder in the repository. I’m not going to go over the steps in detail as there are ample SVN tutorials out there, but you will basically create a folder structure in your repository with trunk, tag, and branch folders and set it up so that the contents of the /web folder on your local machine reflect the contents of the /trunk folder in the repository. My repository for a client project looks like this:
/clientName
/branches
/tags
/trunk
/css
/images
/index.html
/about.html
…..
So you can see that the trunk contains everything that would be in the website folder that you’d upload to a live server. If you also want to version other site assets, you can create additional folders under the /trunk directory. I usually create a /docs folder and a /working folder for frequently changed assets that I want to be able to access on many machines. Note that files that don’t change are not in this setup. For example, I don’t put the clients web design questionnaire or the .pdf of the signed development agreement in this structure.
B. Start developing your site on the local machine, working in the /client_1/web directory as you normally would. Each time you make a signifigant change, you commit the change to the repository. As you work with SVN more and more, you will decide when you need to commit your changes. I usually commit every 30 minutes or so, unless I’m working on something more critical whereby I commit more frequently. If I’m adding a new page for a client and adding the text, I usually will create the page and add the text and then commit to the repo. If I wanted to I could commit once I’ve created the page, and then commit again when the content is done, but I don’t find that practical. You, however, will find what’s practical and what works for you.
C. Stop and create tags at major intervals. When I’m first building a site I make very frequent use of tags. Recall that tags are a snapshot frozen in time of your site. When I’m building a site I often make sweeping changes to the css, and that’s why I commit and tag frequently. I may have 20-30 development tags in early development while I’m working on the site structure and cross-browser testing (though I do my browser testing with each tag creation. as I like to pickup browser compatibility issue early on).
Once I’m happy with the site structure and I’ve tested it in multiple browsers, I make tags less frequently. Often I’ll complete sections of pages in a website and then create a tag. Once the site is complete and I have it to show to the client, I also create a tag. I then make the required corrections and changes (with more tags if needed) and then for the final release, I create a final tag.
In terms of versioning my tags, I like to keep all development versions under 1.0, as I save the release version for a website for 1.0. As I make updates to the site I will increment the version number. Major changes to the site (a new section, new feature) will sometimes get a tick up to 2.0 — but only for very signifigant changes.
D. Moving tag contents to a testing server. This step is the only major limitation I see with my svn web development workflow — and if you the reader has suggestions I’d love to hear them. Currently when I want to upload a tag to a web server (development server or live server ), I export the tag to the local machine. My tags are named based on my personal version system, for example, “helpspa_tag_0.5.1” , so I export the tag from the repository and place it in the client’s folder, in the /webBackup directory (recall that we created this folder in the beginning of this article). I now head to the /webBackup/helpspa_tag_0.5.1 directory and I upload the files to the testing (or live) server.
E. Maintenance and Corrections. Clients often make changes to websites, and it’s my practice to create a new tag for each set of changes that a client requests. So if a client calls me tomorrow and asks me to make 5 changes to 4 different pages, I make the changes and save this set of changes as one tag. I document what these change are in the commit box, of course, but I see no reason to create a new tag for every single change. Note that if the client only wanted one change I would still create a single tag, but when multiple changes are requested in one “set”, then this set becomes a tag.
III. LIMITATIONS AND WHAT I’D IDEALLY LIKE TO BE ABLE TO DO
A. There’s no easy way to go from the SVN repository directly to the FTP server (testing or live). There are services that will perform an FTP push every time you commit, but that’s not useful for me. Often I’m committing work in progress that isn’t ready for people to see (e.g it doesn’t work yet), so I really only want to move to the FTP server when I’m ready — which in my case is usually when I create a tag.
And the reason I use the export feature and go from the tag in the /webBackups directory as opposed to copying directly from the /web directory is because the files in the /web directory also have hidden /svn folder that track change information. While you can upload the website with these files, for very large sites it really increases the upload time. So exporting is way you can get a copy of the site without having to deal with these hidden files.
B. I’d like to get Dreamweaver involved. Another limitation of my system is that I’m not synchronizing. If you are using Dreamweaver and you’ve set it up properly, you can very easily make a correction to a couple of files, and then only upload these files as needed and not the whole site. Now if I remember what’s changed I can just upload the single files from the tag directory in /webBackup, but often times I don’t remember what files I changed and I wind up re-uploading the entire site. And while this isn’t a deal-breaker, I’d like to improve this part of my workflow.
C. I’m not branching. At this time I’m not really using branches in my workflow and I’m not sure that I need them. I’ve read mixed reviews of SVN’s ability to branch — some people think it’s great while others report it to be a disaster. In the future I will consider looking at Mercurial. Mercurial is a DVCS (distributed version control system) that is fundamentally different from SVN in many different ways. According to what I’ve read, many people have said that Mercurial does a significantly better job with merging branches back into the trunk than SVN. At this time, however, SVN still offers a ton of popularity and resources for you if you have questions. In the future I will look at Mercurial and see if there’s a case for Mercurial in a web development workflow.
The preceding workflow is my own creating for getting subversion to fit into web site design. Please feel free to leave comments to let me know where this workflow can be improved. In the next article in this series, I will review SmartSVN, the program that I use as a GUI for Subversion (coming soon).