You are here: IRS>Smart Web>CvsRepository (10 Nov 2008, WikiGuest)

*SMART CVS Repository*

The SMART repository is managed with the Concurrent Version System (CVS) to allow several people to work on the software at the same time
and to manage the organization and documentation of changes as the software evolves.

Full documentation about CVS can be found at Cyclic Software.
An excellent and readable overview is available here.
CVS can be used as simply or as baroquely as you choose, but we have no need or desire for complication with SMART.

This guide will evolve as work on SMART progresses, but the key points to remember are that most mistakes can be undone
and if you have questions not addressed here contact our CVS manager Don Barry.

This guide is divided into two parts.

  1. The use of CVS from the command line.
  2. Preferred way - EMACS is used to make changes and to automatically integrate them into the CVS repository.

*CVS Setup*

To access the SMART repository, which lives on isc.astro.cornell.edu, you must have an environment variable CVSROOT set to the value (replace user with your user name) :

> :pserver:user@isc.astro.cornell.edu:/home/cvs

If you use the csh or tcsh shells, this is done with:

> setenv CVSROOT :pserver:user@isc.astro.cornell.edu:/home/cvs

either manually or in your .cshrc file for automatic execution at login.
Users of sh or bash can place:

CVSROOT=:pserver:user@isc.astro.cornell.edu:/home/cvs; export CVSROOT

in their .profile file. You must also set the environment variable "CVSREAD" to any value, for example :

setenv CVSREAD y
or
export CVSREAD=y

You will also need to "log in" to the CVS system (see below). You will only need to do this once on any given machine/network, since the information necessary to validate you will be saved in your home directory under the .cvspass file.

*Why we use CVS*

The basic principle behind CVS is that you "check out" a working copy of the software on which you wish to work.
At the end of your modifications, your changes can be merged back into the master tree, along with changes any others have made.
This requires that first, any changes made to the master tree since checkout be retrieved and merged into your local copy, and then, that CVS propagates your changes to the master tree.
This doesn't happen to often, and when it does, the merge usually succeeds without your intervention.

Good software engineering practice dictates that this process of checking in changes (known as a "commit") be done in an optimal fashion. The rules to follow are :

  • Each change set should add/repair/delete a feature or feature set.
  • Each change set should be as small as possible but large enough to encompass a set of related changes. Don't feel compelled to check in every hour or even every day: completed commits are preferred over frequent commits, and changes can be abandoned without side-effect.
  • Each change set should produce, at the end, a codebase which still works. Don't check in changes to the code until you've got something better than what you started with.
  • Each change set should be annotated with a brief note of what you have accomplished in your modifications (CVS automates this).

CVS accomplishes more than just letting people simultaneously modify files. It stores all changes in a modular fashion, so that if on retrospection a modification was a bad idea,
it can be backed out of the code. Any and all revisions of a given file are available at any time. It also provides for management of "versioned releases",
such that at completion of milestones the code can be "tagged" in a highly functional state, and development can continue with unstable code,
while at the same time bugfixes can be submitted to the prior releases. However, this is all icing on the cake.
The advanced versioning work can be handled by CVS gurus and learned by others as their needs grow.
The basic commands below are all that is really necessary for a developer to begin work.

*Basic CVS command-line Cheat Sheet*

The following commands are necessary to perform basic editing with CVS. These will not be needed if CVS is automated with Emacs. (See below.)

To login to the CVS server (only required once per home directory), use:

cvs login
You will need to have the proper environment variables set.

The CVS command:

cvs checkout smart
will retrieve the SMART project into a directory named smart beneath the current directory. This directory can be anywhere you have privilege to create it, it needn't be in your home directory. This is your "working copy" of smart, where you'll make your modifications. You can have as many working copies as you like -- CVS uses the "copy-modify-merge" paradigm, which means many people can be modifying the exact same file from many different locations!

Periodically, you will want to update this directory with changes which have been checked by others. This is easily done (when inside the working copy directory) with:

cvs update

Two optional commands facilitate development by allowing any authorized user to see who else is editing a given file. Setting the CVSREAD environment variable made all checked-out files read-only by default, as a reminder. To begin editing a file and make it read-write, use:

cvs edit filename

When through editing you can use:

cvs unedit filename
This will lock the file again (it will be read-only).

After you have made a set of related changes and verified that you haven't made catastrophic errors which make the code unusable, check in your modifications with the command:

cvs commit
An editor will appear in which you may enter the description of your change set. You may be asked to perform an update (and possibly resolve a conflict it engenders), if the other changes have been checked into the repository.

*More Advanced Commands*

A few other useful commands are:

cvs add filename
to add a file to the repository.
cvs remove filename
to remove a file from the repository (though it won't be deleted there), after removing it from your working copy. Both of these require a subsequent cvs commit command to finalize.

Since changing filenames and directory names is difficult under CVS, a naming convention must be closely followed for both procedural? and object orientated? programs.

cvs editors filename
shows who has run cvs edit on the file, to give a (possibly incomplete) snapshot of who is working on it. Keep in mind that CVS can accomodate multiple changes made to the same file, merging them seamlessly, and alerting you in the (rare) case of a conflict.

cvs status
gives a brief status for each file (can be run as cvs status filename also), including the revision number, and whether it's up-to-date, locally modified, in conflict with the repository version, etc.

cvs log filename
shows the modification log with revision numbers.

cvs diff -c filename
shows the contextual diff of the local file in your working copy from the version in the repository. You can also specify a revision or release.

cvs history -o -a
shows who checked out what and when. It works best if people use cvs release when they are done with a working copy.

cvs release -d dir
releases and deletes the working directory dir. It's not really necessary, but it logs your intention to abandon a given checked-out module, and makes cvs history actually useful.

*Automating CVS with Emacs*

GNU Emacs ships with an excellent module called vc, which can automate all of the steps of version control with CVS. It works with other version control systems besides CVS too, so some of the terminology differs. The Emacs+IDL SMART mode sets up CVS for convenient use, and is the preferred method for programming SMART.

VC can do all sorts of things for you, but the single basic command used 90% of the time is:

C-x C-q (or C-x v v)
These both run the function vc-next-action which intelligently calls cvs edit,unedit,update,commit as required at that point, prompting you as appropriate. As a convenience, in smart-mode F12 is also set to run this powerful command.

As an example, suppose you've just checked out SMART, and are editing a file foo.pro. If set up correctly, smart-mode will be entered automatically. It is likely read-only ("%%" in the mode line). C-x C-q will check out the file and mark you as editing it. You perform some changes, and use C-x C-q again. The frame will split, and you will be prompted to enter a change comment, and enter C-c C-c when done. You can continue to code and add comments, or to commit your comment now. Upon invoking C-c C-c from the comment buffer the file is checked in (committed) and made read-only, and you are marked as no longer editing it.

The full set of vc commands is also available in the Tools->Version Control menu. It can add files to the repository,

VC also automates resolving conflicts (the rare case when two developers make incompatible changes to the same file), using the additional Emacs utility EMerge.

*Release Tags*

CVS has a wonderful capability which allows all the files in a project to be "tagged" at some level of revision, and then referred to later with this tag as a cohesive "snapshot". Typically, this is most useful for tagging "releases", constituting an entire codebase which is stable, tested, and can be distributed (and referred to in the case you screw everything up!). The creation and maintenance of release tags is best left up to the ISC CVS maintainers, but everyone should know the basic format we'll use:

  • All stable release products (notwithstanding to whom they are released) will be tagged as follows: `!vX_Y', where X and Y are the major and minor release numbers.
    The first release, for example, will be `v0_1'.

  • Bug fixing branches based on each release will be tagged `!vX_Ylatest', if they become necessary. For example, if v0.1 is released (no periods allowed in the CVS tag, hence `v0_1'),
    and bugs are found in it which need to be addressed immediately, while simultaneously new and unstable development continues on the main branch,
    the bug-fixing branch would be tagged `v0_1latest'. Work on it could proceed without complication, and v0.1.1, e.g., could be immediately re-released.

 
This site is powered by FoswikiCopyright © 2002-2018 by the IRS Team.
Send feedback. We use Foswiki.