RE: Handling project documentation using CVS

[Thornley, David]

> -----Original Message-----
> From: address@hidden [mailto:address@hidden
> Sent: Friday, October 12, 2001 4:28 PM
> To: address@hidden
> Subject: Handling project documentation using CVS
> 
> 
> Hello all, I was wondering if some of you nice people could 
> give me some
> feedback on an issue I've been wrestling with.
> 
> Besides the actual source code to a project, I also need the 
> ability to
> version design documentation ( and maybe other stuff, but this is my
> immediate concern ).   By design documentation, I mean things 
> like Visio
> documents, with UML diagrams, etc.
> 
As opposed to TeX or ?roff documents, I guess.  These are
likely to be proprietary formats best represented as binary
files, which means that they aren't well suited for CVS.

> On one level, I have a feeling that CVS isn't the best way to handle
> versioning these documents.  It kinda feels like using the 
> wrong tool for
> the job. But, on the
> other hand, I can't think of any really, really, solid 
> reasons why NOT to
> do it.
> 
I think it would be more accurate to say that these files aren't
the ones CVS handles best.  I think that a systems that does file
locking better than CVS would do a little better, but nobody's
shown me a system that works much better than CVS.

You have to remember that automatic merging isn't going to work,
and in general the only way to merge is to take one of the versions
and manually recreate the changes.  This means that you want at least
advisory locking, so that anybody starting work on such a file will
know that there's likely to be a conflict that will require redoing
changes.  It also means that, while you can have branches, merging
doc changes between branches will not in general work, and so
it would probably be necessary to redo the work when applying
changes to more than one branch.

CVS won't store the files efficiently, so frequent small changes are
likely to take lots of disk space in the repository.  This may or
may not be important.

If you have another system that does what you need it to do
and has good file locking facilities, then it may or may not
be worth your while to use it to control documentation in a
separate project.  It is likely to do somewhat better than
CVS, but introduces two version control systems and potential
confusion.

> So, if some of you have some experience, or thoughts, on this 
> issue, please
> share them with me.
> 
It works.  It isn't ideal, but it works.