The code base for a site changes rapidly during its development phase. Several programmers may work collaboratively on a given page, and clients most likely will review the progress "live" as code is developed. In this situation it's important to know the status of the code generating a given piece of output. Is it still experimental? Is it stable? Has it been marked for release to the staging or production site? If I spot a problem or feature that wasn't there before, can I peek at the source code or see the revision history of the file to understand what's changed? Now that we're all using version control (you are using version control, aren't you?) this information is being tracked and can be produced automatically.
The vc module provides a simple procedure to display version control information in the page footer. At a glance it gives developers and clients a summary of the page's status and revision history. Here is an example of the one-line summary produced by vc in standard reporting mode:
| Version 1.3 | Last commited: Fri Dec 17 11:17:40 1999 by ron | EXPERIMENTAL |
This tells me the page was generated by version 1.3 of the script, when it was last committed, who checked it into the repository, and what the state of the file is; vc will also display the entire revision history of the file and the source code of the procedure that generated the page. You can see a full demo by visiting the preferences page.
If you're not a fan of version control yet, or you're unfamiliar with the basics of CVS, check out MarkD's Guide to CVS or the on-line CVS Documentation. The rest of this document assumes you know the basics.
To summarize, vc is a development tool that provides the following information as part of the standard page footer:
There are three configuration parameters:
[ns/server/yourserver/acs/vc] ; location of the CVS executable CvsPath=/usr/local/bin/cvs ; default reporting level (Silent, Standard, or Verbose) DefaultReportingLevel=Standard ; do we offer the option of viewing source code? ViewSrcP=1
User's can select one of the following reporting levels in place of the server default:
Silent This turns off the display of any version control information on the pages you view. Standard Displays a one-line footer with the version number, date of last check-in, author, and status of the script that generated the page. Verbose Same as Standard plus the full status report and revision history of the script that generated the page and a link to view the source code.
This is controlled by a non-persistent cookie which the user can set by visiting the preferences page or clicking the Version X link in the footer. vc uses a cookie rather than a table because it is largely a development tool and not part of the "user experience" for a site. On a development server the default reporting level should be Standard, and on a production or staging server it should be Silent. A production server should also set ViewSrcP=0 to disable a client's ability to view the site's source code.
To use vc simply add a call to vc_footer just before the closing
ad_footer or whatever method is used to generated the footer of a page. vc_footer does an exec cvs to gather version control information for the page and then returns a string based on the user's preferred reporting level.
The only "parsing" that vc_footer does is a translation of the CVS state tag for a file into a more meaningful message. The conventional tags are Exp (Experimental, the default), Stab (Stable), and Rel (Released). Any other tag will be displayed as Unknown by vc_footer. State tags are set using the command cvs admin -s tag file.
Might be nice to integerate with things like the ticket tracker or general comments on a page.
As written these procs are tied specifically to CVS, but they could be extended to work with RCS or SCCS repositories, or any other revision control system we might adopt in the future.
Not sure how gracefully this will break if things are missing, but you can always turn it off.