Informational Files
In the top level of the distribution tree, you'll find several files
containing useful information (and pointers to further information).
They are, in approximate order of importance:
- NEWS – This file lists the changes from one release to the next,
in reverse chronological order (that is, most recent first). If you've
already been using CVS for a while and have just upgraded to a new
version, you should look at the NEWS file to see what new features are
available. Also, although most changes to CVS preserve backward
compatibility, noncompatible changes do occur from time to time. It's
better to read about them here than be surprised when CVS doesn't behave
the way you expect it to.
- BUGS – This file contains exactly what you think it does: a list
of known bugs in CVS. They usually aren't show-stoppers, but you should
read over them whenever you install a new release.
- DEVEL-CVS – This file is the CVS "constitution". It describes
the process by which changes are accepted into the main CVS distribution
and the procedures through which a person becomes a CVS developer. You
don't really need to read it if you just want to use CVS; however, it's
highly interesting if you want to understand how the mostly
uncoordinated efforts of people scattered across the globe coalesce into
a working, usable piece of software. And of course, it's required
reading if you plan to submit a patch (be it a bug fix or new feature)
to CVS.
- HACKING – Despite its name, the HACKING file doesn't say much
about the design or implementation of CVS. It's mainly a guide to
coding standards and other technical administrivia for people thinking
of writing a patch to CVS. It can be thought of as an addendum to the
DEVEL-CVS file. After you understand the basic philosophy of CVS
development, you must read the HACKING file to translate that into
concrete coding practices.
- FAQ – This is the CVS "Frequently Asked Questions" document.
Unfortunately it has a rather spotty maintenance history. David Grubbs
took care of it until 1995, then he (presumably) got too busy and it
languished for a while. Eventually, in 1997, Pascal Molli took over
maintenance. Molli also didn't have time to maintain it by hand, but at
least he found time to put it into his automated FAQ-O-Matic system,
which allows the public to maintain the FAQ in a decentralized manner
(basically, anyone can edit or add entries via a Web form). This was
probably a good thing, in that at least the FAQ was once again being
maintained; however, its overall organization and quality control are
not on the same level as if a person were maintaining it.
The master version of the FAQ is always available from Molli's Web site
(http://www.loria.fr/~molli/cvs-index.html, under the link
"Documentation"). The FAQ file shipped with CVS distributions is
generated automatically from that FAQ-O-Matic database, so by the time
it reaches the public it's already a little bit out of date.
Nevertheless, it can be quite helpful when you're looking for hints and
examples about how to do something specific (say, merging a large branch
back into the trunk or resurrecting a removed file). The best way to
use it is as a reference document; you can bring it up in your favorite
editor and do text searches on terms that interest you. Trying to use
it as a tutorial would be a mistake – it's missing too many important
facts about CVS to serve as a complete guide.