Instructions for Zope Docs CVS repository with targeted write privileges

Here is a draft of instructions for our targeted-write public CVS arrangement - one having write-privileges selectively targeted at people outside of digital creations. Due to CVS pserver's widely reputed insecurity, we can't just do the simple thing and just use it.

The simpler pserver approach is considered adequate for read-only public access does use - see here for instructions.

Requirements

The arrangement utilizes SSH for robust authentication, so anyone using it will need to be able to conduct CVS over SSH. (This should be straightforward on Unix-like systems, given the availability of SSH and CVS there. See towards the bottom for info about arranging for use on MS Windows. My instructions, below presume Unix.)

The checkins go via classic.zope.org, and require accounts on that machine per user doing the checkin. Digital Creations folks can use their existing classic.zope.org accounts (or have a regular one created), and we use a script to set up special accounts, restricted entirely to CVS, for others.

Any remote user with checkin privileges will have to provide an SSH RSA public key. We also need to know for which repository section they're getting privilieges, so they can be added to the respective groups for that repository.

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 login script - .bash_profile in bash. It will affect 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. It's worthwhile getting acquainted with ssh-agent - check the man pages.

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 situatated, 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 bookeeping 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. If you're using ssh-agent, it'll take care of that for you, hoorah.

Updates

Once you've checked out the hierarchy you can synchronize your copy of the contents by entering the 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. There are other useful options - check the cvs man page...

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>

producess 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 checkin, and can be very handy for identifying the changes you made for your checkin summary.

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

Committing changes

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

To checkin in all changed files in a directory, issue the command:

      cvs commit

To checkin particular files:

      cvs commit file1 file2 ...

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

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.

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

Emacs

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.

CVS under SSH on Windows

Martijn Pieters forwards info about setting up up SSH CVS access on Windows with WinCVS (http://www.wincvs.org/) - instructions are at:

http://www.wincvs.org/faq.html

The instructions in step 4 are for NT only. On Win9x you'll have to edit Autoexec.bat, adding the following lines:

        PATH=%PATH%;"C:\SSH"
        SET HOME=D:/HOME

to append the path to the SSH client to the PATH environment variable (with DOS style backward slashes, in this example C:\SSH), and to set a home directory (with UNIX style forward slashes and no quotes, in this example D:/HOME). A reboot is required.. sigh.