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

From: Jeff King <peff@peff.net>
Date: Mar 24, 2009, 03:14 UTC
Message-ID: <20090324031448.GA12829@coredump.intra.peff.net>
In-Reply-To: <20090323195304.GC26678@macbook.lan>

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.

Show 11 quoted lines

> +[[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