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

$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:cstrong@cvs.acme.com:/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":http://www.cvshome.org/docs/manual/cvs.html.

  This document is written in structured text.  For a quickie intro to
  structured text, look
  "here":http://www.zope.org/Documentation/Articles/STX.
