OPENSTEP 4.2
PVCS Adaptor Bundle User's Guide

Overview

This document describes the usage of the Project Builder PVCS integration provided by the PVCS_Support bundle.  It is assumed that you have access to the PVCS Version Manager product and its documentation.

Topics Covered

This tutorial covers the following topics:

	- Layout of the "SCM" User Interface
	- SCM Operations
		- Creating a new Work Directory from an existing Repository
		- Adding files to the Work Area
		- Locking Files
		- Checking in Changes
		- Tagging Files
		- Updating a Work Area
		- Miscellaneous Operations

Before you begin...

Before following this tutorial, you must:

	- Install INTERSOLV PVCS
	- Configure the PVCS_Support bundle in PB and the defaults database
	- Create a PVCS Repository

Note:   When creating a repository with PVCS, using the "Project Assistant" is recommended.  When prompted to add directories to the repository, make sure you "Add with Subdirs..." in order to incorporate all of the subdirectories in your project.

User Interface Layout

The SCM user interface consists of menu items, a main panel, and auxiliary panels.  This section briefly describes the layout and functionality of these widgets.

SCM Menu Items

Most of the SCM operations may be performed via the SCM menu items.  The menu items are located under the "SCM" submenus of ProjectBuilder's "Project" and "File" main menus.

Project-->SCM
	Show Panel 
		Displays the SCM Panel.
	Show Console 
		Displays the SCM Console.
	Create Work Directory 
		Displays the Create Work Directory panel.
	Merge Files 
		Puts all project files into the SCM Panel and selects SCM's Merge operation in the panel.
	Stamp Files 
		Puts all project files into the SCM Panel and selects SCM's Stamp operation in the panel.
	Check In Files 
		Puts all project files into the SCM Panel and selects SCM's Check-In operation in the panel.

File-->SCM
	Show Panel 
		Displays the SCM Panel.
	Check In Files	
		Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Check-In operation in the panel.
	Lock Files
		Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Lock operation in the panel.
	Unlock Files	
		Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Unlock operation in the panel.
	Stamp Files
		Puts files selected in ProjectBuilder into SCM Panel and selects SCM's Stamp operation in the panel.
	Show Changes
		Diff's the files selected in ProjectBuilder with their corresponding repository head versions.

SCM Panel

Most of the SCM operations may also be performed via the SCM panel.  To display the SCM panel if it's not already visible, click the Project-->SCM-->Show Panel menu item.  The panel consists of five UI elements:

	- Table View
	- Update Status Button
	- File Status Filter
	- Miscellaneous Operation Buttons
	- Core Operations Popup Button

Table View

The SCM table view contains rows representing a single file in the PB.project.  The table view shows the files associated with the project in a flattened way, whereas ProjectBuilder arranges the files hierarchically in it's main project window.  The first column of the table view shows the status of the files relative to the head of the repository.  Since multiple users may be making changes to the repository, the status is never guaranteed to be totally up to date, although the statuses are sync'd with the head of the repository right when the project loads into ProjectBuilder.  The second column in the table view displays the path of the file relative to the main project directory. 

Update Status Button

Located in the upper right corner of the SCM panel is the "Update Status" button.  The user may periodically click the "Update Status" button to update the local file statuses relative to a snapshot of the repository head at the time the update button is clicked.     

File Status Filter

To the right of the table view, and below the "Update Status" button, is a file status filter popup button.  The filter button indicates that only files with the given status will appear in the table view.  For instance, to show only those files that are locally modified, select "Modified" in the filter popup button and the table view should change it's display to show only the files whose statuses equal "Modified".  To show all files in the project, switch the filter popup button back to "All Files".  Note that changing the filter does not run the status command, it just shows the currently known statuses.

Miscellaneous Operations Buttons

Below the filter setting you'll find miscellaneous operations buttons (Show Changes and Display History).  See the Miscellaneous Operations section later in this document for information on these functions.   

Core Operations Popup Button

Below the miscellaneous buttons you'll find the operation popup button.  In order to perform an SCM operation you first need to select the files in the table view which you wish to operate on.  Once you've selected the proper files, choose the operation you wish to perform in the operation popup and then click the "Execute" button.  The operation will be performed and the output of the command will be written to the SCM console (display the console by clicking the Project-->SCM-->Show Console menu item).  If there is a fatal error during the execution of the command the user will be notifiy via an alert panel.  The user may also be prompted to enter additional information before the command is executed (like a check-in log message, for instance).    See the sections later in this document relating to the SCM operations for more information.

SCM Auxiliary Panels

In addition to alert panels displaying important SCM errors, there exist a few auxiliary panels:  

	- SCM console
	- Log Entry Panels 

SCM Console

The SCM console, which displays pertinent repository log messages, may be made visible by clicking the Project-->SCM-->Show Console menu item.  The console is read-only, but it may be cleared periodically by clicking the "Clear" button located at the lower right of the panel.  

Log Entry Panels

The "Check-In" and "Stamp" log entry panels appear automatically when the respective "Check-in" or "Stamp" operations are performed.  These panels prompt the user to enter a repository log message for each of these operations.  See the Checking in Changes and Stamping Files sections later in this document for further information.

SCM Operations

The following sections describe SCM functionality for the following operations:
	
	- Creating a New Work Directory
	- Adding/Removing Files in the Work Area
	- Locking/Unlocking Files
	- Checking In Changes
	- Stamping Files
	- Merging the Work Area
	- Miscellaneous Operations

Creating a New Work Directory

Follow these steps to create a new work directory:

	- Display Create Work Directory Panel
	- Set Work Directory and Repository Location
	- Create and Open New Project

Display Create Work Directory Panel

Once you've created (and/or located) the source code repository, select Project-->SCM-->"Create Work Directory" from the ProjectBuilder main menu to create a new work area.  This will bring up a panel that prompts you for the repository location and the local work directory location (the directory into which your local work area will be created).  

Set Work Directory and Repository Location

You may click the "Set..." buttons next to the text fields on the panel in order to bring up a file browser will will allow you to graphically select the directories.  You may also take advantage of path completion in the fields by typing a partial path and pressing your user defined path completion key (default is F2 on OpenStep/Windows).  

Create and Open New Project

Once the directory information is complete, click "Create" to create and open the project.  During the creation process, a local copy of the repository will be checked out into your local work directory, and the corresponding PB.project will be opened in ProjectBuilder.   Once your local work directory is created you should never need to create it again.  Simply opening an existing PB.project that was previously created with SCM should activate the SCM system for that project.  An existing PB.project may be opened by either double-clicking on the PB.project file in the Windows file viewer, or by opening the project inside of ProjectBuilder via the Project-->Open... main menu item. 

Adding/Removing Files in the Work Area

Whenever you add or remove files from the project using ProjectBuilder's add/remove files functionality, the SCM system is automatically notified about the changes and acts accordingly. 

Add Files

If you've added a file, SCM will add that file to the list it maintains for the repository and mark that file's status as "Added".  You must select the file and "commit" the operation to write that file to the repository.  If the operation is successful the file's status is set to "Up-To-Date".  

Remove Files

When removing a file from the project, SCM immediately removes that file from the list it maintains and there is no need to commit the operation to the repository.  Under PVCS files are never actually removed from the repository (they'll only be removed from the PB.project).

Locking/Unlocking Files

Lock Files

The PVCS source code repository system requires that users lock files in the repository that they are currently working on to prevent others from making changes to the files simultaneously.  If you have your defaults set up correctly, the SCM bundle will lock files in PVCS automatically when you begin editing them in ProjectBuilder (see the section on setting up ProjectBuilder in the SCMReleaseNotes.rtf).  In order to lock files manually, select the desired files in the table view, select "Lock" in the operation popup, and click the "Execute" button.  This will lock the selected files and prevent others from modifying them in the repository.  Note that if you attempt to lock a file that has a newer version in the repository, the lock will fail and the file status will be set to "Needs Update".  See the section on Merging a Work Area later in this document if that situation occurs.

Unlock Files

You can unlock files in two different ways:  

1.  Select the files and then "Unlock" them using the SCM panel operation.  
2.  Check-In the desired locked files - if the check-in is successful the files will automatically be unlocked.

Checking in Changes

Follow this process to check in changes:

	- Identify and Verify Modified Files 
	- Execute Check-In Operation

Identify and Verify Modified Files

If you have locally modified files (status equals "Modified") you may elect to check your changes into the repository.  The file status must also indicate that the file is "Locked" (status should read "Locked and Modified") since PVCS requires files to be locked before check-in.  If the file isn't locked (status just says "Modified"), select the unlocked/modified files in the table view and then choose "Lock" in the operation popup.  Click the "Execute" button to lock the files.  Once the files are locked you will be able to proceed with the check-in only if you have the latest version of the files checked out.  If you don't, the file status will read "Needs Update".  Select the files needing update in the SCM table view and execute the "Merge" operation to update the files (see the section Merge Work Area later in this document).  Once this checklist is complete you should be able to check in the files. 

Execute Check-In Operation

Select the modified/locked files in the SCM table view, select "Check In" in the operation popup, and click the "Execute" button.  A log panel will open prompting you to enter a log message describing the changes you are about to check in.  After you've entered your message click 'OK' and the check-in will occur.  If you click 'Cancel' the check-in will be aborted.  

Stamping Files

You may elect to stamp a set of files in order to distinguish the current versions in some special way.  For instance, you might stamp the files in your project with "Release01" to indicate that the current repository versions correspond to "Release01" of your software.  In order to stamp your files select the desired files in the table view, choose "Stamp" in the operation popup, and click the "Execute" button.  A panel will appear prompting you to enter a string which will be used to identify the stamp.  Enter something in the text field and click 'OK' to proceed.  If you click 'Cancel' the operation will be aborted.

Merge a Work Area

You may elect to merge the contents of the repository head into your local files.  The need to do this would arise if someone else checked-in changes to the repository which you haven't incorporated yet.  If your file statuses have been updated recently enough, files that are in an intermediate state which requires updating will have their files statuses set to "Needs Update".  To update your local files select the desired files in the table view, select Merge in the operation popup, and then click the "Execute" button.  Ideally, the SCM system will be able to perform the merge without conflicts.  However, if you revert the merged file to saved and find that the merge resulted in conflicts, you'll need to fix the conflicts before you attempt to check in your changes.

Miscellaneous Operations

Show Changes

The "Show Changes" button on the SCM panel will launch FileMerge and diff the files selected in the SCM table view relative to the corresponding repository head versions of those files. 

Display History

The "Display History" button will display the repository history information (in the SCM console) on the selected files in the SCM table view.  In order to view the history the SCM console must be visible.  To make the console visible, click the Project-->SCM-->Show Console menu item.