Version Control for Web Development using CVSby Ron Henderson (ron@arsdigita.com) Submitted on: 2000-06-30
ArsDigita : ArsDigita Systems Journal : One article
Running a Web development project is a complex process. As a
project leader, you will need to coordinate the efforts of a
programming team, one or more graphic artists, content managers, and
testers, all while dealing with site objectives that necessarily
evolve over time. If you want to sleep at night, every piece of
static content required to make your Web service operate should be
under version control. This includes all server-side scripts,
static html pages, images, template specifications, data models, and
anything else your site requires to operate.
A good version control system serves two related functions: record
keeping and collaboration. Record keeping is the more obvious. What
state was the code in yesterday? What changes have taken place since
the last feature launch? Who made change X that broke page Y?
Typical version control systems achieve this by recording each change
to a file as a separate numbered revision, along with a message
about what the change was and who made it. This fosters collaboration
by making it easier for one developer to understand what the others
have done (they can read the log messages, and look at the isolated
changes). Good systems provide mechanisms for merging changes from
multiple developers so that work is never clobbered accidentally.
At ArsDigita we have selected the free, open-source Concurrent
Versions System (CVS) as our standard version control system. CVS is
based on the copy-modify-merge model, and works as follows: A
master copy of the the project is stored in a special area called the
repository. One or more working copies of the project
can be checked out of the repository. Each contributor to the
project makes changes in one of these working copies and then
commits those changes, along with a log message about what they
did, to be recorded in the repository. At any time the working copy
can be compared to the master copy and, if necessary, updated
by merging in the more recent changes.
Anyone can pick up the basics of CVS in a few minutes by reading
the documentation, available online at
http://www.loria.fr/~molli/cvs/doc/cvs_toc.html).
You really only need a handful of commands: add, remove, commit, and
update. This article is geared toward more advanced features of CVS
that come into play during the overall management of a Web development
project.
A typical Web development project involves three servers, which may
be on one or more physical hosts (see http://arsdigita.com/asj/cvs/).
We need a production server for the live site, a staging
server to test changes before they go live, and a development
server for more long-term or unstable development. In CVS terms, each
one is served from a different working copy of the project. We
also need at least two Oracle users/tablespaces to separate
production/staging from development. Here we concentrate on
initializing the project's code repository.
Putting a new project into a CVS repository is called
importing. For the sake of example, assume that you're setting
a new project called "myservice" based on the ArsDigita Community
System (ACS) version 3.1.5.
This creates a new repository in
Note that this command is executed from inside the
top-level ACS subdirectory, not above it. The example above will create a new project repository rooted at
Note that the repository does not have to reside on the same host
as the working copies. In fact, CVS is network transparent:
the repository can be accessed anywhere on the internet using one of
four connetion methods. At ArsDigita we only use the ext
(external transport agent) method with Secure Shell as the actual
transport agent. For this to work the environment variable
You now have a fresh installation of ACS to start from. Use the
regular cvs commands to add new files
and directories to your repository (see http://www.loria.fr/~molli/cvs/doc/cvs_7.html#SEC60), and remind your developers to
get in the habit of committing their changes regularly.
Often you want to get a quick summary of the status of each file in
your project. You can use cvs update to do this. This command
compares the state of each file in your working directory with the
corresponding file in the repository, merging changes from the
repository if newer revisions have been committed. You can use update
in preview mode to check the state of everything:
We get a quick view of the state of the project: M is a
locally modified file with uncommitted changes, U indicates
there is a newer revision in the repository (committed from some other
working copy), C indicates a file with unresolved conflicts,
and ? is a file that CVS has no version control information
for.
When multiple files are sent to the repository they receive the
same log message, making it possible to recombine a batch of changes.
You can use a simple third-party tool called cvs2cl.pl to
convert the raw CVS log entries into a GNU-style ChangeLog. This is
extremely useful for recording the change history of a project.
To generate the ACS ChangeLog for the last week of April:
Advanced CVSAs stated above, the basics of CVS are quite easy to pick up. There are a few other commands beyond the scope of this article that are worth looking up:
TagsTags provide a symbolic name for a collection of revisions. Creating tags is easy:% cvs tag acs-3-2-2-R20000412 It might help to visualize a tag as a straight line through a particular set of revisions of each file of the project:
When you checkout a copy of a project, by default you receive the latest revisions on the main line of development, also called the trunk. But you can also uses tags to request a particular named snapshot of project: % cvs update -r acs-3-2-2-R20000412 % cvs checkout -r acs-3-2-2-R20000412 Note that for tags to be useful, somebody (the project leader) needs to plan a system for creating them at critical times in the project's history. For the ACS we record each toolkit release using a special tag of the form: acs-major-minor-release-date This intentionally mimics our release version numbering (see http://arsdigita.com/doc/release-numbering) so that the exact code shipped out in a particular release can be recalled from CVS. BranchesAt certain times it's important to separate the project into separate, parallel lines of development. For example, prior to a release we split the main project into a release branch and a development branch. On the release branch we freeze the code and fix bugs in preparation for the release, while on the development branch we continue development for the future. The idea is simple:
The branch has a label (acs-3-1), and revisions along the branch have four digits instead of two. The command to create a branch is: % cvs tag -b branchtag Once created you have to explicitly move your working copy onto the branch with a cvs checkout or update. Example: % cd /web/arsdigita % cvs tag -b acs-3-1 % cd /web/ % cvs checkout -r acs-3-1 -d acs-staging acs You know that a particular file is on a branch because cvs status tells you: % cvs -d /usr/local/cvsroot checkout -r acs-3-2 acs % cvs status acs/readme.txt =================================================================== File: readme.txt Status: Up-to-date Working revision: 3.1 Mon Feb 21 07:02:06 2000 Repository revision: 3.1 /usr/local/cvsroot/acs/readme.txt,v Sticky Tag: acs-3-2 (branch: 3.1.4) Sticky Date: (none) Sticky Options: (none) Branches are only used in the ACS repository to isolate code prior to a release. CVS supports branching to an arbitrary depth, but it's hard to imagine needing more than two parallel lines of development. Note that branches created this way always even-numbered (3.1.4.1). As described below, the import command also uses branches to separate your changes from the code imported from an external vendor. These so-called vendor branches are always odd-numbered. Merging changesWe just spent a week working on the new release, fixing bugs and typos. All of those changes were commited to the release branch so that work in the development area could continue in isolation. Now that the release is over, we want to merge all of those fixes back into the trunk so they don't have to be fixed again for the next release. In CVS terms, we need to merge the release branch and the development trunk.
Another way to think about it: we want to create a patch comprised of all the changes that took place along the acs-3-1 branch and apply that to our development copy. This is another job for CVS update using the -j (join) option to merge in a selected set of changes. % cd ~/develop % cvs checkout acs % cd ~/develop/acs/ % cvs update -kk -j acs-3-1 % cvs commit -m "merged changes from acs-3-0 branch" The arguments to update are -j acs-3-1 to merge in all changes that took place along the acs-3-1 branch, and -kk to kill keyword expansion so we don't get spurious conflicts from CVS keywords in the source files. What if you want to go in the other direction, merging changes on the trunk with a release branch? % cd ~/develop % cvs checkout -r acs-3-1 acs % cd ~/develop/acs % cvs update -kk -j HEAD % cvs commit -m "merged changes from development" You can find a complete description of branches and merging in the context of toolkit releases in the document ACS Release Mangement (http://www.arsdigita.com/doc/runbook/acs-release-management). Upgrading ACSAs ArsDigita programmers we always want to develop using the latest version of the ACS. Why is this important?
Several weeks have gone by since you started developing the site, and now a new version of ACS has been released that contains features you need or bug fixes to important modules. In the meantime, you've customized parts of the basic toolkit software necessary for the project. How can you upgrade your ACS installation without losing the customization? The solution is to merge the new release with your existing code base using vendor/release tags to keep track of where the code came from. This is essentially the same principal that applies to merging branches in CVS. You supply a symbolic name for the vendor and software release of the new code you're importing. CVS then checks each file against the code in the repository, merges all the changes, and reports any conflicts so you can resolve them. For the most part this process should simply upgrade the existing files in your repository so they reflect the latest release. Conflicts should only arise if you and ArsDigita (whom we treat here as an outside software vendor) made overlapping changes. Starting the upgradeThe basic steps are simple. Here is the upgrade method based on
|
|