= Reporting bugs in cvs-fast-export =

CVS is a wretched hive of scum and villainy.  Lifting a CVS repository
into a clean revision history is difficult and has rebarbative edge
cases. If you are reading this, you have probably tripped over one
of them.  Here is what to do about it.

== Reduction ==

First, reduce the test case to a minimal set of CVS files that will
reproduce the misbehavior. The cvsconvert wrapper script should be
useful for getting a concise summary of errors visible at tagged
locations and branches.

There is a tool called 'cvsreduce" in the cvs-fast-export
distribution.  It makes a skeletonized copy of a CVS repository,
dropping out all the content but leaving the metadata in place.
Revision comments are replaced with their MD5 hashes, very short 
but still unique.  

The skeletonization process has the additional benefit of removing any
sort of data that might be sensitive; only filenames, revision dates
and committer IDs are left in place.

A conversion attempt on the skeletonized repo should raise the same
errors as the original did (except for ignorable ones involving CVS
keyword expansion, which will all go away when the file is
skeletonized).  If it does not, try skeletonizing with -t instead
to preserve non-sticky tags

Now try to make the skeletonized repository as small as possible by
removing swathes of files from it, checking each time to make sure the
error continues to reproduce. It is best if you can reduce the fileset
to a single file or pair of files.

You should find you can simplify the directory structure by moving
files from subdirectories to the root, doing file renames to avoid
mame collisions. Neither moves nor renames should change the errors
reported except in the obvious way of changing pathnames in the
messages.  Again, if the errors do change in any other way this is
interesting and should be reported.

At the end of this process you should have a handful of skeletonized
master files.  

== Transmission ==

Make a tarball including the CVS masters. Make a session transcript
showing the error relicating on them.  Mail these things to the
maintainer with any other information you think might be relevant.

== Compensation ==

Wrestling with CVS repository malformations is ugly, hard work.

If you are requesting help on behalf of an open-source software
project, you will get help for free as the maintainer's schedule
permits.

The maintainer is available on a consulting basis to all others
and *will* expect to be paid for his pain.  

// end

