How to use the TDB "closed" CVS repository for submitting
review material
These instructions pertain to the reviewers in the active review groups
of the NEA TDB project who wish to deliver material to the NEA for
inclusion in the review reports using the TDB closed CVS repository.
These instructions are not valid for the TDB "open" CVS repository,
through which it is only possible to download and view files, not edit
and upload.
CVS is short for "Concurrent Versions System", and is a software in
the public domain that has been around for a while, and together with
SCCS and RCS is one of the most popular systems for software version
control. These systems aim to solve some of the problems that arise
when many people are working on the same set of files, and when one
has a set of files that are continuously updated and it is necessary
to keep track of the different versions and changes.
You do not need to install any special software on your local computer
to use the TDB CVS repository. However, if you are curious about the
software used, you can find
the latest version of the CVS software itself at
the Cyclic.com web site. This site
stores software releases as well as a lot of useful information. The software
distribution comes with an extensive manual in texinfo format; this
manual is also available in HTML format (see links from the Cyclic.com
web site).
If you wish to install CVS on your computer (which, as stated, is not
needed or even useful for utilising
the TDB CVS repository), you must
also have a working RCS system, the software for which can be
downloaded from any site which mirrors
GNU software.
The CVS software itself has many advanced and nice features for people
who work with large sets of files. To make full use of CVS, one must
use a command-line interface, preferably under Unix. As this is not
really an option for most of the participants in the TDB project, we
use a WWW interface to the CVS software, built on the CVSWebEdit
software. The version used at the TDB web site has been
extensively modified.
The principal reasons for the TDB project to use
a version control system such as CVS are the following:
It stores and retrieves multiple revisions of text. CVS
saves all old revisions in a space efficient way.
Changes no longer destroy the original, because the
previous revisions remain accessible.
CVS maintains a complete history of changes.
CVS can resolve access conflicts. When two or more people
wish to modify the same revision of a file, a locking mechanism
alerts the programmers and helps to prevent one modification from corrupting
the other.
CVS automatically identifies each revision with name,
revision number, creation time, author, etc.
CVS minimizes secondary storage. CVS needs little extra
space for the revisions (only the differences).
Although the above list is no mean feat in itself, it must be
mentioned that the CVS web interface only has a very restricted set of all the
functionality offered by the original CVS system. This is partly due
to the technical problems associated with
accessing sets of files via a web browser rather than directly through a
CVS server. However, for the reasons listed above,
it still offers valuable advantages over not having a CVS repository.
Using a CVS repository, it will hopefully be possible for the members
of the TDB review teams to instantly check the status of the review
report, and to edit the files that make up the report themselves and
submit the changes in a convenient way. The alternative is
a system where all reviewers have to submit
their requested changes via e-mail or whatever to the NEA, which then
has to make all the changes, have them checked by the reviewers
etc. Hopefully, the CVS repository will speed up the work
considerably.
The files in the CVS repository are handled by the CVS software. The
idea is, that the versions of the files in the repository should be
the latest and greatest versions submitted. When a reviewer wants to
make changes to a section in a review report, he or she first locks the
file in question. Locking the file ensures that nobody else can submit
a new version of this file as long as the lock is left in
place. Anyone who so wishes can still download the latest submitted
version of the file, but only the person who has locked it can upload
(submit) a new version. In order to ensure that no changes are
accidentally deleted, it is very important to always
lock the file one wants to edit
download the latest version of the file from the CVS repository
edit that file
upload/submit the new version of the file and unlocking it
(unless one wants to continue editing it).
If you don't follow this procedure, but use an old working copy of
the file on your computer for editing,
and then submit this version as soon as you
can (when noone else has the file locked), you risk "losing" changes
made to the file by others (or even yourself) since you last
downloaded it, in the sense that the latest version submitted will
contain one set of changes and not another, rather than being a
synthesis. It is still, however, always possible to retrieve any
previous version of the file from the CVS repository, since CVS stores
all submitted versions of the files in the repository.
To use the TDB CVS repository, make sure you have a recent version of
the Netscape or Internet Explorer web browsers installed.
Internet Explorer versions before 5.0
can not do uploads, so you should upgrade to the latest version if you
plan on doing uploads. At the NEA, we currently use Netscape version
4.7 or later, so if you use this, all features of the CVS repository
should work. Please notify
of any problems you encounter.
You also need a password and user name as a TDB reviewer to be able to
access the CVS repository. Use the same password and user name as you
use for accessing other parts of the TDB web site. Only review team
members and the NEA secretariat have access to the various
subdirectories containing review material.
The file hierarchies in the CVS repository can be browsed by clicking
on the names of subdirectories. When you click on the name of a
subdirectory, all the files in that subdirectory will be displayed. If
you click on "Download directory", all files in that
directory, including all lower-level subdirectories, will be
compressed to a gzipped tar-file, which can be downloaded and
uncompressed with WinZip or some
other program. Use this when you really want the latest versions of
all files in a particular subdirectory.
To browse the CVS repository, you click on the names of the
individual directories (e. g. "Word templates/"); this will bring up
the contents of that directory, including any subdirectories which can
then again be clicked on etc. To download an individual file, see the sections below.
This procedure should only be used when you just want to look at a
file without planning any changes to it. If you are planning to edit
the file, use the procedure described below.
To download a file without locking it, browse
the directory structure until you find the file you are looking for,
and then click on
"text view/download", if it is a simple ASCII
text file, such as e. g. a LaTeX file, a PostScript (PS) or
Encapsulated PostScript (EPS) file.
or "binary download" if it is a non-ASCII file such as e. g. an
MS-WORD or PDF file.
Depending on the browser you use, and on the default settings for
downloading different types of files that are present in your browser,
it may be necessary to (under Windows) click the right-most mouse
button to get binary downloading to work correctly.
If your browser displays the whole file in the browser window when you
click on "text view/download", you can use the browsers functions for
saving the file ("Save as...") to get it onto your local storage media.
On MacIntosh systems, it may be necessary to take special action to
make the operating system understand that the file downloaded is of a
particular type (MS-Word, e. g.). Consult your local Mac guru for
information about how to do this.
This procedure should always be used when you want to edit an
existing file in the CVS repository. Otherwise, it is very easy to
inadvertently overwrite changes made.
Browse the directory hierarchy to find the file you want to edit.
Click on "edit file" to go to the file edit form. If you get
the message that the file is not locked by anyone, it is OK to go
ahead and lock, download and make changes. If it is already locked
by someone else, you must either communicate with that user or wait
until he/she unlocks the file.
Assuming the file is not locked by anyone else, click on "Lock
file" to lock this file. The fact that you have the file locked does
not mean that noone else can download the file, but it does
mean that only the person who locked the file can upload new versions.
Click on "Download" to download the file to your local computer.
Edit the file on your local computer.
When you have finished editing, upload and unlock the file using
the menu item labelled "Upload". If you wish to make a more recent
version available in the CVS repository, but will continue editing
locally, you can reset the check box in the upload menu that
indicates whether or not the uploaded file should be unlocked or not.
It should be noted, that when uploading to update an existing file,
the name of the file on your local computer doesn't matter; it will be
changed to whatever the original name of the file was before being
deposited in the CVS repository.
If you have a completely new file (rather than a new version of an
existing file) that you wish to put in the CVS repository, first
browse to the subdirectory where you want to put the file, and then
click on "Import new file to this directory". This will bring up a
form that will let you browse your local machine for the file you want
to upload, as well as giving a different name to the file once
uploaded. You must click the "Submit" button to carry out the upload;
until you do that, nothing is changed in the CVS repository.
It is important to check that you have the check-box for binary files
checked if you are uploading binary files, and that it is not
checked for ASCII text files, such as LaTeX files.
With CVS, you can always check what has happened to a file over time
by clicking on the "Revision history" field for a certain file. If the
file is a text file, you can also view the "diffs", i. e. compare two
versions of a file using the links in the revision history page for a
file. There are some buttons at the bottom of the file that let you do
"diffs" between arbitrary revisions.
Unfortunately, this mechanism does not work for binary files such as
MS-Word files. For these, you have to download the two revisions you
want to compare, and use MS-Word's own comparison mechanism to see
what has changed.
If you delete files in a directory, these are not completely removed from the
CVS repository; rather, they are placed in the "Attic". This is a special
directory that contains deleted or otherwise obsolete files, so they can
be retrieved if necessary. To access these files, click on the button "Show
attic directories" (if it is not present, there are no files in the "Attic").
This will then show an additional directory "Attic", which contains previously
deleted files.
