################################################################

$RCSfile: TUTORIAL.txt,v $

Author: Craeg Strong

$Date: 2002/08/21 05:50:42 $

################################################################

Contents

1. Getting Started
2. Creating the Registry
3. Checking out your Sandbox
4. Creating a CVSFile instance
5. Performing Simple CVS commands

Getting Started

Before getting started with CVSFile, there are a couple of pre-requisites.

Make Sure Zope is properly installed and Running

Any 2.4.X or 2.5.X release should work fine.

Make Sure CVS is properly installed and Running

Make sure you have CVS up and running. If the CVS server is different than the Zope server, make sure that CVS (client/server) is properly installed on the Zope server. One easy way to do this is to type "cvs --help" at the command line. If you get a usage message, you're in! To find out the proper value for CVSROOT, ask the person who set up CVS. It is usually a directory, like /repository/cvsroot if you are using regular CVS, or a connection string, like :pserver:[email protected]:/repository/cvsroot, if you are using CVS client/server. Note this value as 'CVSROOT'; you will need it below. NOTE Since CVSFile does not yet provide support for doing a "cvs login" through the web, if you are using CVS in client/server mode, you will have to manually do a cvs login on the Zope server before executing any CVSFile commands.

Make sure that the Zope server userid has access to CVS sandboxes

Either you are going to use CVSFile with a set of pre-existing CVS sandboxes, or you are going to create new sandboxes. Or both. Either way, the userid under which the Zope server is running is going to be reading and writing files (and creating new files) in these sandboxes. One way is to make the sandboxes group +rw and put the Zope server userid in the same group as the developers/content authors. In any event, be sure to test this by assuming the Zope server userid and, from the commandline, trying out some simple cvs commands in the sandbox directories you will be using with CVSFile. Note that the sandboxes must be physically accessible on the Zope server machine (i.e., either local, NFS mounted, etc.).

Make sure that both ExternalFile and CVSFile are installed

See example in INSTALL.txt One way to check is to go to the Products folder within the Zope Control_Panel folder. If CVSFile and ExternalFile both show up, you are in business. Now would be a good time to read the README files for both products, available from their respective README tabs.

Make sure that you have a test CVS module to work with

If you do not have a test CVS module, here is a quick way to create one:

    [UNIX commandline]

    cd /tmp
    mkdir cvsTest
    cd cvsTest
    [ create the file /tmp/cvsTest/testfile.txt with some content ]
    cvs import -m "testing" cvsTest aVendorTag aReleaseTag
    cd /tmp
    rm -r cvsTest

    [Win32 commandline]

    cd c:\tmp
    mkdir cvsTest
    cd cvsTest
    [ create the file c:\tmp\cvsTest\testfile.txt with some content ]
    cvs import -m "testing" cvsTest aVendorTag aReleaseTag
    del testfile.txt
    cd c:\tmp
    rmdir cvsTest

Make sure that you have a test sandbox to work with

If you do not have a test sandbox, here is a quick way to create one:

    [UNIX commandline]

    cd /tmp
    mkdir sandbox
    cd sandbox
    pwd          (record directory path for later -- see BASEDIR below)

    [Win32 commandline]

    cd c:\tmp
    mkdir sandbox
    cd sandbox
    dir          (record directory path for later -- see BASEDIR below)

Creating Your Registry

Now in the ZMI, you should see CVS Sandbox Registry in the Add drop down menu. If you don't, try to start up your Zope using the -D (debug) option and see if you had any problems. Review Getting Started above.

First, create a test Folder of the Root Folder. We will do everything within this test folder so we don't mess up anything important.

Now, within your test Folder, select CVS Sandbox Registry to add a registry. Enter the following values for Standard Information:

    ZopeID:      testRegistry
    Title:       My Test Registry
    Description: A registry for testing the CVSFile product

and the following for 'Default Sandbox Information':

    Sandbox Name:   mySandbox
    Base Directory: (BASEDIR above, either /tmp/sandbox or c:\tmp\sandbox)
    CVSROOT:        (the value you noted above as CVSROOT)

Now hit the Add CVSSandboxRegistry button. You should see a happy message.

Checking out your Sandbox

Select your sandbox registry in the ZMI. Now click over to the Sandbox tab. You should see a message indicating that you cannot perform any operations until you select a sandbox.

We will now select a sandbox. Click over to the Registry tab. Notice that the one and only sandbox in the list (mySandbox) lists a yes under isDefault but nothing under isSelected. Now click the round radio button to the left of the mySandbox line in the list, and hit the Select button. Navigate back to the registry by clicking on it (by default you will be back in the Registry tab). You should notice that there is now a yes in the isSelected column.

Now click back over to the Sandbox tab. You should notice that the form is now available for use. Change the module to checkout to cvsTest, and hit the CVS Checkout Sandbox button. Notice the output in the text box.

Creating a CVSFile instance

Now that we have a sandbox with a file in it (testfile.txt), we would like to create an object within Zope so that we can access the contents of the file through Zope and edit it through the web using the ZMI.

In the ZMI, navigate back into the test Folder. Select CVSFile from the Add menu. Notice how the form lists the registry we just made, and provides a link back to its Registry form to change our selected sandbox.

To create a Zope object pointing to testfile.txt, simply type the following:

    [If Zope server running on UNIX platform]

    Target Filepath on server: cvsTest/testfile.txt

    [If Zope server running on Win32 platform]

    Target Filepath on server: cvsTest\testfile.txt

And hit the Add CVSFile button. You should see a happy message. If not, try again.

Performing Simple CVS Commands

Now navigate to your CVSFile instance-- notice that it was automatically assigned testfile.txt as its Zope ID, since you did not supply anything different.

The Edit tab comes up by default. You may edit this file as normal through the web. Lets try putting in a whole bunch of garbage in the file, and hitting the Save Changes button.

You are simulating a situation where you have changes to a file that you have not checked in (committed) to the repository, and you realize that you really do not want these changes. The Revert button was made for this situation.

Click on the CVS tab. First, hit the CVS Update File button and verify that the file, indeed, was modified. What you are seeing is the output directly from the update command. For details on its interpretation, please see the CVS manual (URL below). Suffice it to say that the M stands for locally modified.

Now click on the CVS Revert File. To verify that your changes have been thrown away, click back on the Edit tab.

Now, make some further (non garbage, in theory) edits in the Edit tab, and click Save Changes. Now click back to the CVS tab and enter some crucial changes in the Commit Message field, and click the CVS Commit File button.

If you now click the CVS Update File button, you should see (no output), meaning that the local copy is now in sync with the version in the central repository.

Have fun with CVSFile!

Notes

More details on CVS can be found in the CVS manual.

This document is written in structured text. For a quickie intro to structured text, look here.