Re: [PATCH] Add warning about known issues to documentation of cvsimport

[Jeff King <peff@peff.net>]

On Mon, Mar 23, 2009 at 08:53:05PM +0100, Heiko Voigt wrote:

> The described issues are compiled from the tests by Michael Haggerty and me.
> Because it is not apparent that these can be fixed anytime soon at least warn
> unwary users not to rely on the inbuilt cvsimport to much.

I think this change is good in concept.

> +[[issues]]
> +ISSUES
> +------
> +Problems related to timestamps:
> +
> + * If timestamps of commits in the cvs repository are not stable enough
> +   to be used for ordering commits
> + * If any files were ever "cvs import"ed more than once (e.g., import of
> +   more than one vendor release)
> + * If the timestamp order of different files cross the revision order
> +   within the commit matching time window

Reading this, I kept waiting for the "then" to your "if". I think the
implication is "your import will be incorrect". But it would be nice to
say _how_, even if it's something as simple as "changes may show up in
the wrong commit, the wrong branch, be omitted" or whatever. Just give a
general idea of what can happen.

Also, this renders somewhat poorly in the manpage version. I get:

<quote>
ISSUES
       Problems related to timestamps:


       ·   If timestamps of commits in the cvs repository are not stable
           enough to be used for ordering commits

       ·   If any files were ever "cvs import"ed more than once (e.g., import
           of more than one vendor release)

       ·   If the timestamp order of different files cross the revision order
           within the commit matching time window
       Problems related to branches:


       ·   Branches on which no commits have been made are not imported
</quote>

Note the extra blank line between each heading and its list, and the
lack of a blank line between the end of the first list and the heading
of the second. Your source is very readable, so it really is just
asciidoc being silly, but I wonder if there is a way to work around
that.

-Peff