Thermochemical Database (TDB) project

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.

Contents

What is a CVS repository?

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.

Why use a CVS repository?

The principal reasons for the TDB project to use a version control system such as CVS are the following: 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.

How does the CVS repository work?

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
  1. lock the file one wants to edit
  2. download the latest version of the file from the CVS repository
  3. edit that file
  4. 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.

How to use the CVS repository for up- and downloading files

Prerequisites

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.

Directories

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.

Individual files

Browsing the CVS repository

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.

Download without locking

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 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.

Edit files

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.
  1. Browse the directory hierarchy to find the file you want to edit.
  2. 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.
  3. 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.
  4. Click on "Download" to download the file to your local computer.
  5. Edit the file on your local computer.
  6. 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.

Uploading new files

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.

Checking the revision history and retrieving old versions

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.

What are the "Attic" directories?

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.

 

Related links

TDB introduction

Latest project news

General information

Other thermochemical database sites

E-mail contact: 

 

Restricted areas

The following links are password-protected.

TDB Phase II home page

TDB Phase III home page

Last reviewed: 27 May 2011