Instructions for Zope Docs CVS repository write-privileged access

Here is a rough draft of instructions for the Zope Docs CVS arrangement. Due to the reputed insecurity of the CVS pserver, the simplest approach won't do - we have to do a bit more work to provide a service with a modicum of security.

Requirements

The arrangement utilizes SSH for robust authentication, so anyone using it will need to be able to conduct CVS over SSH.

Any remote use with check-in privileges will have to provide an SSH RSA public key for their docs* account. We will also have to decide to which of the "books" they will have check-in privileges, so they can be added to the respective groups.

Procedures

I'll form all my examples as for a test account, docstest. You would substitute your own account name where it appears.

For all actions

For all actions you need to have an environment variable, CVS_RSH defined to the value "ssh". For bourne shell/bash:

      CVS_RSH=ssh; export CVS_RSH

It's a good idea to have this in your .bash_profile. It will effect anything where you use the cvs :ext: mode. Everywhere that ssh makes an RSA-key connection for cvs it will require your passphrase for that key. You can use ssh-agent to stash that key once for your shell, and not have to specify it again while you're issuing commands from the same shell.

Checkout

To checkout the cvs Zope docs, from the unix shell

cvs -d :ext:[email protected]:/cvs-repository checkout ZopeDocs

Presuming all the authentication has been correctly situated, the passphrase for your key will be required (you will be prompted unless ssh-agent is taking care of it for you), and when you satisfy that the ZopeDocs directory hierarchy will be situated in your current working directory.

There are cvs checkout options that allow you to specify an alternate name for the directory - check the cvs man page or info file for details.

The cvs bookkeeping in the checked-out directory hierarchy keeps track of the repository server and account for you, so you don't specify them again when working within the hierarchy. However, this means that all updates and revision actions you take within the hierarchy will require the passphrase for that account.

Updates

Once you've checked out the hierarchy you can synchronize all revisions to the contents by entering the ZopeDocs hierarchy and issuing the command:

      cvs update -d

The -d means to do the update for any nested subdirectories as well as the current directory. You can omit that to update only the current directory, and you can affect only a part of the hierarchy by entering the part you want to update.

The update process actually reconciles your current version of the contents with the versions currently checked in to the repository. The merges are easy when changes you've made from the version you checked out occur in different places than the changes from that version which were checked in to the repository - both sets of changes are kept. The resulting conglomeration may not be right, but oftentimes it is. When your changes and repository changes collide, CVS keeps both, delimited by text markers consisting of bunches of <<<<<<< less-than, ======= equals, and >>>>>>> greater-than signs. Then you have to remove the delimiters and pick and choose the correct changes � perhaps in collaboration with the author of the conflicting version.

Examining differences

The cvs command

cvs diff <file>

produces a unix diff of your version of the file against the checked in version. This can be a must for detecting conflicts and helping to reconcile them before check-in, and can be very handy for identifying the changes you made for your check-in summary.

Options enable you to specify particular versions for comparison, among other things.

Committing changes

Using the cvs check-in command you can check-in particular changed files, or all the files in a directory that have changed.

To check-in in all changed files in a directory, issue the command

cvs commit

To check-in particular files

cvs commit file1 file2 ...

(CVS records for the files will be locked during the check-in, so you cannot run other cvs commands against them in the meanwhile. If you want to identify the differences for your check-in summary with cvs diff, for instance, you'll need to do that before issuing the check-in.)

At this point CVS will launch an editor for you to enter a summary of the changes, for the cvs logs for the file(s). The default editor on unix is vi - if you want something else to be used, set the environment variable 'EDITOR':

      export EDITOR=ed

Adding files and directories to the Zope docs hierarchy

To add a new file to the zope docs hierarchy:

      - first create the file

      - 'cvs add <file>'

      - 'cvs commit <file>'

The file is not added until you do the commit.

Adding directories is a little different - they are committed immediately when you do the add command.

In general, be sure you know what you're doing and that it fits in with the overall Zope Docs mission - most structural changes like additional files and, even more, directories, should probably be done by the central folks.

Miscellaneous

For emacs users, emacs provides a fairly nice interface to cvs (and rcs) with something called vc. In order to use it with this scheme you'll have to be using ssh-agent, since vc doesn't provide for out-of-band password prompting. Consult your emacs documentation or wizards for more info on vc. This is a draft of the procedures we will be using, stay tune for more formal instructions.