Web Site
Developers
Selecting a Source Control System*
An Overview
In an introduction to this series I wondered if I was making a mistake by not employing a source control system from the onset. However, given the exigencies I was working under (as I am today, only worse) I opted to try to do without it. While that may not have been my wisest choice, it worked in the interim. Nonetheless, source control system is still just a tool that will aid me, but will not solve many of my problems that are common to web site development. Therefore, this could be no more than clutching at straw as I am overwhelmed.
The forte of source control systems is tracking multiple, diverse changes within the set that combine to build a product. Web sites using nearly static pages are not so amenable to giving an out sized return as the usual coding project. Here we have distinct files where the content is completely different from page to page with only the barest structural components that are reused. Thus, from the onset our expectations must be lessened.
If you were writing a large format such as a book that undergoes several revisions, source control could be of benefit. Here, at best, it will help keeping the templates and the css file under better protection and obsolete formats will be more easily avoided. When we begin to use dynamic paging with routine calls to a back end database, revision control will become much more important. Keep this bromide in mind too: "your mileage (i.e. return on your investment) may vary".
Selection Process
Version (or source) control systems are not new to me, however, that is primarily true as a user not an administrator. Nonetheless, I wanted to keep it simple enough to use nearly immediately, however, have sufficient flexibility to make major, differing choices later. Therefore, I may have both over valued the term flexibility and mistakenly thought it meant I could reconcile conflicting code easily. Those issues colored the choice I made.
My efforts began with several Google searches that listed mostly free offerings, such as this one that includes links with just a bit about the application itself. That was the starting point. A more detailed listing that attempts property characterization of a more limited subset that included a couple of proprietary packages I had used. The latter helped me select Subversion package.
Subversion was not what I had expected to have been my choice, since I went in thinking I might try Git. The latter was overkill as is Subversion given my current needs. At present, the installation is local with just a single user. Nonetheless, I was attempting to think ahead where a central repository could be installed on one of our servers, which would allow remote, distributed access to several developers. These latter considerations were part of the reason I ended up with Subversion.
Package Necessities - Documentation
Documentation and access to problem resolution was also part of the selection process. Subversion has an on-line book [1.] for the recent, stable version along with a mail list that I have so far not needed. I assure you that does not imply I had no difficulties.
Package Necessities - Error Recovery
I still barely know my way around the system, since I am at an early section of Chapter 2 "The Basics". Nonetheless, I had been successful enough in mucking up the first installation that I did a full new installation (after cleaning out the first) and thought myself well upon my way to a second. The second installation proved to be unnecessary for me when I recognized I misunderstood the meaning of "/path/to/repos" where the latter portion was to be taken literally. Commands that failed previously worked. Moreover, I was able to clear out the incorrect project directories and recreate them with mostly gaining the outputs the documentation showed. Not perfect, but for now it suffices for me.
The issues of making radical changes in the future are important. Choices we believe are good in hindsight can appear extremely poor with greater experience and knowledge. Therefore, I always highly valued the ability to make changes without the necessity of completely fresh start. So far, Subversion has met those tests.
Package Setup for Use
Let it suffice by my saying I have a Debian Linux variant, hence, I am using an older version of Subversion than is the most current, stable version. The bigger generic issue is once you have your source control system installed, you need to understand the steps required to accept projects. In Subversion's case, it is necessary to create a base repository:
svnadmin create /path/to/svn/repos
where repos is to be taken literally, a number of subdirectories are found that govern the source control features of your application just beneath repos/. These can be seen with the listing command, provided you have the rights to be the administrator. My personal preference is to be a regular user without administrator's rights.
The next step is to create a project the the version control system keeps tabs. Again for my linux system it looks like this:
:~$ sudo svn import /local/path/Documents/OST-1/ \
file:///etc/subversion/repos/OST-1/ -m \
"Near to current version, incomplete" \
--editor-cmd "emacs" --username "theuser" \
--password "openforme"
The documentation I referred to early suggests a bit more refined path than I thought necessary for this project. Next note, I am unsure my default selections were effective, however, as you will see below I have been able to get a copy of the project repository as a user with no special rights. Back to creation of the project repository, here is what follow the command above:
Adding /local/path/Documents/OST-1/howto Adding /local/path/Documents/OST-1/howto/HowTo-template.html Adding /local/path/Documents/OST-1/floss Adding /local/path/Documents/OST-1/floss/OSS-template.html Adding /local/path/Documents/OST-1/ceo Adding /local/path/Documents/OST-1/ceo/ceo-template-page.html Adding /local/path/Documents/OST-1/index Adding /local/path/Documents/OST-1/css Adding /local/path/Documents/OST-1/css/style-sheet.css Adding /local/path/Documents/OST-1/page-1 Adding /local/path/Documents/OST-1/page-1/index.html Adding /local/path/Documents/OST-1/page-2 Adding /local/path/Documents/OST-1/page-2/index-2.html Adding /local/path/Documents/OST-1/page-3 Committed revision 1.
Well the first version was accepted. Now lets run a quick check to see how it was taken:
:~$ svn list file:///etc/subversion/repos/OST-1 ceo/ css/ floss/ howto/ index/ page-1/ page-2/ page-3/
The directory structure seems right, however, no files are shown. Next if we run the check out routine, we see the entire copy. This differs form my previously my experience where one checks out single or, at most, a few files upon a request, each individually. Early on in my first try I began as root and even began to edit the files, which I was not really comfortable. However, once I received my own set:
:~$ svn checkout file:///etc/subversion/repos/OST-1 A OST-1/howto A OST-1/howto/HowTo-template.html A OST-1/ceo A OST-1/ceo/ceo-template-page.html A OST-1/floss A OST-1/floss/OSS-template.html A OST-1/index A OST-1/css A OST-1/css/style-sheet.css A OST-1/page-1 A OST-1/page-1/index.html A OST-1/page-2 A OST-1/page-2/index-2.html A OST-1/page-3 Checked out revision 1.
which were editable, I changed over to a regular user. Nonetheless, I am uncertain my changes will be accepted when I attempt to check the set back into the system. In any case, I also took a new file that I began as root, which required changing the ownership to myself as a user. I am editing this file at this moment. It is the one you are reading. After I pull in a test version of the site's css file I will attempt to update the changes as an unpriviliged user. If that fails, it will take just a bit more work to do it an another user with root rights. Thus, the core of the site will be updated soon.
Another in the Series
How To: Coding html and css files by hand. It is my intention to show what benefits I have learned to extract for a version control system. The appearance of the next article is unpredictable, but we will be discussing this in the near future.
Corrections, suggested extension or comments write: How-To-Guy. If the mailto does not work, use this: hcohen[-At-]bst-softwaredevs.com.
© Herschel Cohen, All Rights Reserved
Return to Home or Tools Page
____________________________________________________________________
1. Also available in several other formats and a copy may be
purchased O'Reilly. Return
* Originally published on the Open Source Today site August 21, 2007. Content may have been altered prior to being moved onto Web Site Developers.