README.txt #1

$Id: //guest/perforce_software/utils/vsstop4/dev/README.txt#1 $

Microsoft Visual SourceSafe (VSS) to Perforce converter

Summary
=======

- Obtain and install a version of Perl for your machine. This script
  assumes you are running on Windows (as it reads registry settings
  for date and time). You can download a precompiled binary from
  http://www.activestate.com/. Note that this script has been tested with Perl 5.6.

- Install P4Perl from http://public.perforce.com//guest/tony_smith/perforce/API/Perl/index.html.
  This is the Perl interface to Perforce and is required because it is significantly faster 
  than executing p4.exe at the command line.
  I tend to use the Current version (for Perl 5.6 or 5.8 as appropriate), and just double-click on
  Windows installer and run it (no real need to download and save). E.g.:

http://public.perforce.com/guest/tony_smith/perforce/API/Perl/current/p4perl56-setup.exe or
http://public.perforce.com/guest/tony_smith/perforce/API/Perl/current/p4perl58-setup.exe

- Ensure both Perforce's "p4" and SourceSafe's "SS" command can execute correctly.
  Add the directory containing SS.EXE to your path, then try running "ss".
  (see setenv.bat for example setting)

  You must use Visual SourceSafe version 5.0 or later.
  Test Perforce by running "p4 info". The Perforce depot can be empty or not.
  The Perforce server need not run on the same machine you are running
  the converter on, however it may be wise to do so to avoid network
  traffic. Accessing VSS repository over a slowish network will definitely
  slow things down - SEE IF YOU CAN COPY VSS REPOSITORY LOCALLY FOR CONVERSION.

- Untar or Unzip the converter on a disk large enough to hold all files
  stored in VSS, plus the space required for the "metadata".
  The directory you put the converter in must not be under the Perforce
  server root!
  Also advise not having spaces in the path.

- For improved performance, see the tips below (which require extra modules to be
  installed).

- If you are not a superuser in your depot then you will get
  error messages since the script tries to update date/time and
  username in changelists and labels - limited to superusers.

- Change directory to the directory the converter was installed into and
  edit the file "config.ini" to setup for your environment.

- Make sure that you do not have a client workspace called "vss" or whatever you specified
  as p4client in config.ini since it will be overwritten by the script.

- Then run "perl convert.pl" (note Performance tips below before doing this).

- Note that many sites have reported failures mid-way through conversions
  due to corruption in the SourceSafe database.  The only way around this
  used to be to determine what files SourceSafe has corrupted and fix them somehow.
  You can now use the "exclude" option in Config.ini file to ignore some directories
  if that makes your life easier, especially if used in conjunction with the "vsscorrupt"
  flag.

Performance
===========
The script can take a long time (many hours) to run if you have a large VSS repository. The
script needs to parse the history of VSS and then get individual versions of each file out
and check them in to Perforce. This by its nature takes time (and driving VSS from the command
line is slow). To ensure the fastest possible conversion:

- Copy VSS repository locally (and use a fast machine!)

- For larger installations with large labels, try installing the Perl module DB_File.
  Running the following command:
    perl -e "use DB_File;"
  will give an error message if it is not installed.
  To install, use PPM (Perl Package Manager from ActiveState - installed with Perl):
    c:\ppm
    PPM interactive shell (2.1.5) - type 'help' for available commands.
    PPM> install DB_File

- Try setting the config.ini option "vss_use_ole" to yes - this uses VSS OLE Automation instead
  of ss.exe from the command line. It can be faster (but not always). Note that this requires the
  full VSS to be installed locally, and in particular the OLE interface which is usually to be found
  in "C:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SSAPI.DLL" to be installed and
  registered.
  Note that if you set this option to "yes" you will need to provide values for vss_user and vss_password.
  ****WARNING****: if you get OLE Exceptions using this option (e.g. it can be more sensitive to VSS repository
  corruptions than "ss get"), then just turn this option off.


It is highly recommended, that you read the following before
attempting to do the conversion.


Differences between VSS and Perforce
====================================

VSS defines a hierarchy of files using the concept of a "project",
which is essentially just a versioned directory.  The current
project must be set specifically before any VSS operation.  The
information stored by VSS is stored in a proprietary format.

Perforce stores an arbitrary tree of files which can be mapped to
multiple clients independently using any 1:1 mapping.  Perforce
uses RCS format files to store revisions, but all metadata
is stored in a single, central database.

Perforce uses the notion of an atomic change which may consist of many
add, edit, and/or delete operations.  It is guaranteed that either all
of a change is visible, or none of it is.  VSS does not provide atomic
change transactions.


VSS implements branching by "sharing" files among projects, then "branching"
them by breaking this link.  There is no record of merging activity.

In Perforce when you wish to create a "branch", you simply copy the files,
typically to another directory.  The recommended convention
is to make the second component of the depot pathname
the branchname.  Thus, when it is time for the main line of development
to be released as v7, you would typically do a
"p4 integrate //depot/main/... //depot/v7/..."
which (since there aren't any files in //depot/v7 currently) would create
copies of all files in //depot/main in //depot/v7.  To refer to the mainline
version of foo.c use //depot/main/foo.c; for the v7 branched copy, use
//depot/v7/foo.c

This works well because Perforce implements a lazy copy.  Archive files
are never duplicated; only the metadata changes.

Merging operations are recorded in Perforce - if, for example, patches
were made to v7 code these patches could be merged back into the main line
of development with "p4 integrate //depot/v7/... //depot/main/..."
Only files which have changes that have not been previously integrated
into main will be integrated, and the integration will be recorded so
that next time those changes will not have to be revisited.

Because VSS lacks information on merging operations, the converter
simply imports files as they existed in VSS.  Because the branching
models are quite different and adjustments will have to be made
after moving to Perforce, the converter does not attempt to infer
any branching relationships.  It is highly recommended that the first
step after conversion is to identify directories which have a branching
relationship and establish this relationship in Perforce.  Contact
Perforce Technical Support (support@perforce.com) for help with this.

Labels are commonly used in VSS; they are available in Perforce but not
usually needed.  Perforce uses atomic change transactions, and thus the
state of the depot or any part of it is easy to specify.


Restrictions and limitations
============================

Filenames may not contain ASCII unprintable characters, at signs
(@) or hashes (#).
Note that the converter changes things like German umlauts in filenames.

VSS files cannot start with a dollar sign ($) or contain colons
(:) - these restrictions do not exist under Perforce.

Userids and labels may not contain spaces or ASCII unprintable characters.
These characters will be mapped to underscores.

The converter currently does not record any file deletions or renames, partially because
it's extra effort to do that but also because it's impossible to do it
properly; Visual SourceSafe simply will not give any history information
for files which are currently deleted.

Sort order is based on time but VSS does not output seconds; it is thus
possible that two checkins will appear to be at the same time when they
weren't.  This may result in two revisions of a file appearing to be out
of order.

Corrupt dates (later revisions newer than earlier) may cause problems with
labels since the converter takes the label to refer to the next real
revision (not a label revision) rather than the closest revision in time.

The converter is not regularly tested against old server versions, and thus
it is not guaranteed to always work against all older versions.  Unless
you have a good reason to use an old server version, you should run the
converter against the latest version of Perforce.

If your comments contain lines with 17 ore more asterisks in a row, the
extraction of metadata stops there and the conversion is only partial.
If this happens to you either fix readhist.pl or just edit the VSS comments.



How does the converter work?
============================

The converter works in four phases:
Phase I:   extract VSS metadata
Phase II:  improve the metadata (sort and compact changes using a heuristic)
Phase III: execute appropriate VSS and p4 commands
           to construct Perforce database
Phase IV:  niceties after the fact

The "ss properties" and "ss history" commands are used to extract the
metadata from VSS. Hierarchical "ss dir" commands are used if vss is indicated as
being corrupt since corrupt directories can be avoided.

When the converter runs it reads configuration values from the file "config.ini".
See the comments in "config.ini" for a description of each option.


How do I check the end result, and what does it all mean?
=========================================================

If you want to be certain that the revisions stored in Perforce are
correct, answer yes to the question "Do you wish to verify the result?"
(If you say no and then change your mind, just run "perl verify.pl").
The verification step isn't done by default because it takes a long
time, and because there is no portable way to determine whether earlier
phases of the converter succeeded.

You can verify that all changes were successfully submitted by running
"p4 changes -s pending"; it should produce no output.  Look in
the directory "metadata" for files containing a mapping of all VSS
files and revision numbers to the associated Perforce filename and
change number.  The sorted, more human readable version is in the file
"mapping"; the tabular version is in "mapping.ns" (ns for "not sorted").

Change numbers should not be confused with version numbers.  To see the
files and versions affected by a particular change, type

p4 describe -s <change_number>

(Without the -s all differences between files involved in the change are
displayed as well).

To see the list of all changes (you may want to pipe this through more):
p4 changes

To see the list of labels:
p4 labels

To see the list of changes affecting a particular file:
p4 filelog filename

To list revisions associated with the label "labelname":
p4 files @labelname


A note about re-running the converter
=====================================

If you want to re-run the converter it would be best to erase the directory
tree "data", so that there cannot be any conflicts between runs.  If you
don't want to keep the results of the previous conversion, delete all
files in the server root and directories below it.


originally by James Strickland (james@perforce.com)
Modified by Robert Cowham (robert@vaccaperna.co.uk)
Modified by Peter Steiner (peter.steiner@hugwi.ch)