Recipe 9.4. Tracking and Documenting Site Changes

Problem

You need to keep an ongoing record of modifications to pages on your web site.

Solution

Use one or more of the following methods to keep track of how your site evolves over time. If you need just a visual or documentary record of changes (rather than older versions of code that you can revert to):

• Add comments to your code when you make changes.

• Make notations about changes in an offline log book.

• Print pages before changing them and add them to the log book.

• Create an offline database (for example, in FileMaker Pro or Access) and record page changes in it.

If you need to keep a copy of the actual code from older version of your web pages:

• Save an offsite copy of each page before you change it.

• Keep multiple, regularly scheduled backups of your entire site.

• Use a site management tool (such as Macromedia's Dreamweaver/Contribute combination) to automate the creation of "roll back" versions of pages that get changed.

• Consider setting up a concurrent versions system (CVS) for your site.

Discussion

The web has a "here today, gone tomorrow" quality to it. A web site's page inventory can grow and change without regard for the print media tradition of keeping back issues or older editions of previously published material. Web surfers have adapted to this mindset: when a missing page elicits more than a shrug or furrowed brow, they have Google caching, the Internet Archive, or someone else's web site to fall back on. But a wise webmaster looks both forward to what's next for her site, while keeping an eye on (and a record, or better yet, a backup of) what's come before.

Backups are a key part of both choosing a provider to host your site (see Recipe 1.3) and running and maintaining your site on a daily basis. When last week's removed page becomes next week's update, a backup copy of old pages can be a big time-saver.

If your hosting service does not back up your site, consult Recipe 2.7 for information on using the Unix wget to back up files.

For the sites I manage, I use Macromedia Dreamweaver to keep a local copy of the live site, which I then back up daily, weekly, and monthly to my PC's hard drive. For a couple of sites, I also use Macromedia's Contribute to automatically keep the three previous versions (called "roll back" versions) of every page on the site. Dreamweaver also offers webmasters the ability to enable file "check in/check out," which prevents pages from being changed by two people at the same time. A more thorough (although more complicated) solution to tracking and backing up web site changes requires the use of CVS to track and merge simultaneous changes to web page code, but it can be indispensable if site changes must be made simultaneously by multiple editors.

When your web site's design and development are done by a team, adding comments to the code is crucial to making the process go smoothly. It's also a good habit for the solo site builder, even if the comment amounts to just a name, date, and short description of a change made to a page.

Comments are sections of code that appear on the web page. HTML comments, which may span multiple lines, are enclosed by <!--and --> and look like this:

 <!-- 7/15/2005: Added Joe's name and updated bio (DA) --> 

In PHP and JavaScript, single-line comments must be preceded by two slashes:

 // 7/15/2005: Added Joe's name and updated bio (DA) 

PHP also allows single-line comments to be preceded by a pound sign (#), while multiline comment blocks in both languages must be enclosed with /* and */:

 /* This script contains functions    for connecting to the database    and validating user logins    7/15/2005 - Updated database hostname in connection function (DA) */ 

HTML comments add to the file's weight and appear when viewing source; PHP comments do not appear in source or add to the file's weight.

In addition to providing a built-in way to track changes, comments also help explain a complex layout and delineate functions or nested loops in a script to someone else who must edit the code. They also can help you remember why you did something a certain way orin PHP, JavaScript, and other languagesdisable a subsection of code for debugging purposes. For that reason, you might find it useful to use the multiline style in PHP to record permanent information and changes to a script, and the single-line style to temporarily remove lines when trying to uncover and fix a problem.

See Also

Because HTML comments can add to your overall file size, you might want to keep them in your local copy of site files, but remove them from the version that gets published on the web. For more information, see Recipe 4.8. Recipe 2.7 describes how to use wget to back up files on a site.