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

> 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.