254 lines
11 KiB
Plaintext
254 lines
11 KiB
Plaintext
How to write code for CVS
|
|
|
|
* License of CVS
|
|
|
|
CVS is Copyright (C) 1989-2005 The Free Software Foundation, Inc.
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 1, or (at your option)
|
|
any later version.
|
|
|
|
More details are available in the COPYING file but, in simplified
|
|
terms, this means that any distributed modifications you make to
|
|
this software must also be released under the GNU General Public
|
|
License.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
* Source
|
|
|
|
Patches against the development version of CVS are most likely to be accepted:
|
|
|
|
$ CVS_RSH=ssh cvs -d:ext:anoncvs@savannah.nongnu.org:/cvsroot/cvs co ccvs
|
|
|
|
* Compiler options
|
|
|
|
If you are using GCC, you'll want to configure with -Wall, which can
|
|
detect many programming errors. This is not the default because it
|
|
might cause spurious warnings, but at least on some machines, there
|
|
should be no spurious warnings. For example:
|
|
|
|
$ CFLAGS="-g -Wall" ./configure
|
|
|
|
Configure is not very good at remembering this setting; it will get
|
|
wiped out whenever you do a ./config.status --recheck, so you'll need
|
|
to use:
|
|
|
|
$ CFLAGS="-g -Wall" ./config.status --recheck
|
|
|
|
* Backwards Compatibility
|
|
|
|
Only bug fixes are accepted into the stable branch. New features should be
|
|
applied to the trunk.
|
|
|
|
If it is not inextricable from a bug fix, CVS's output (to stdout/stderr)
|
|
should not be changed on the stable branch in order to best support scripts and
|
|
other tools which parse CVS's output. It is ok to change output between
|
|
feature releases (on the trunk), though such changes should be noted in the
|
|
NEWS file.
|
|
|
|
Changes in the way CVS responds to command line options, config options, etc.
|
|
should be accompanied by deprecation warnings for an entire stable series of
|
|
releases before being changed permanently, if at all possible.
|
|
|
|
* Indentation style
|
|
|
|
CVS mostly uses a consistent indentation style which looks like this:
|
|
|
|
void
|
|
foo (arg)
|
|
char *arg;
|
|
{
|
|
if (arg != NULL)
|
|
{
|
|
bar (arg);
|
|
baz (arg);
|
|
}
|
|
switch (c)
|
|
{
|
|
case 'A':
|
|
aflag = 1;
|
|
break;
|
|
}
|
|
}
|
|
|
|
The file cvs-format.el contains settings for emacs and the NEWS file
|
|
contains a set of options for the indent program which I haven't tried
|
|
but which are correct as far as I know. You will find some code which
|
|
does not conform to this indentation style; the plan is to reindent it
|
|
as those sections of the code are changed (one function at a time,
|
|
perhaps).
|
|
|
|
In a submitted patch it is acceptable to refrain from changing the
|
|
indentation of large blocks of code to minimize the size of the patch;
|
|
the person checking in such a patch should reindent it.
|
|
|
|
* Portability
|
|
|
|
The general rule for portability is that it is only worth including
|
|
portability cruft for systems on which people are actually testing and
|
|
using new CVS releases. Without testing, CVS will fail to be portable
|
|
for any number of unanticipated reasons.
|
|
|
|
The current consequence of that general rule seems to be that if it
|
|
is in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK
|
|
to use it without ifdefs (for example, assert() and void * as long as
|
|
you add more casts to and from void * than ANSI requires. But not
|
|
function prototypes). Such constructs are generally portable enough,
|
|
including to NT, OS/2, VMS, etc.
|
|
|
|
* Run-time behaviors
|
|
|
|
Use assert() to check "can't happen" conditions internal to CVS. We
|
|
realize that there are functions in CVS which instead return NULL or
|
|
some such value (thus confusing the meaning of such a returned value),
|
|
but we want to fix that code. Of course, bad input data, a corrupt
|
|
repository, bad options, etc., should always print a real error
|
|
message instead.
|
|
|
|
Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
|
|
operating system or some external interface requires it. We spent a
|
|
lot of time getting rid of them, and we don't want to put them back.
|
|
If you find any that we missed, please report it as with other bugs.
|
|
In most cases such code will create security holes (for example, for
|
|
anonymous readonly access via the CVS protocol, or if a WWW cgi script
|
|
passes client-supplied arguments to CVS).
|
|
|
|
Although this is a long-term goal, it also would be nice to move CVS
|
|
in the direction of reentrancy. This reduces the size of the data
|
|
segment and will allow a multi-threaded server if that is desirable.
|
|
It is also useful to write the code so that it can be easily be made
|
|
reentrant later. For example, if you need to pass data from a
|
|
Parse_Info caller to its callproc, you need a static variable. But
|
|
use a single pointer so that when Parse_Info is fixed to pass along a
|
|
void * argument, then the code can easily use that argument.
|
|
|
|
* Coding standards in general
|
|
|
|
Generally speaking the GNU coding standards are mostly used by CVS
|
|
(but see the exceptions mentioned above, such as indentation style,
|
|
and perhaps an exception or two we haven't mentioned). This is the
|
|
file standards.text at the GNU FTP sites.
|
|
|
|
* Regenerating Build Files
|
|
|
|
On UNIX, if you wish to change the Build files, you will need Autoconf and
|
|
Automake.
|
|
|
|
Some combinations of Automake and Autoconf versions may break the
|
|
CVS build if file timestamps aren't set correctly and people don't
|
|
have the same versions the developers do, so the rules to run them
|
|
automatically aren't included in the generated Makefiles unless you run
|
|
configure with the --enable-maintainer-mode option.
|
|
|
|
The CVS Makefiles and configure script were built using Automake 1.9.6 and
|
|
Autoconf 2.59, respectively.
|
|
|
|
There is a known bug in Autoconf 2.57 that will prevent the configure
|
|
scripts it generates from working on some platforms. Other combinations of
|
|
autotool versions may or may not work. If you get other versions to work,
|
|
please send a report to <bug-cvs@nongnu.org>.
|
|
|
|
* Writing patches (strategy)
|
|
|
|
Only some kinds of changes are suitable for inclusion in the
|
|
"official" CVS. Bugfixes, where CVS's behavior contradicts the
|
|
documentation and/or expectations that everyone agrees on, should be
|
|
OK (strategically). For features, the desirable attributes are that
|
|
the need is clear and that they fit nicely into the architecture of
|
|
CVS. Is it worth the cost (in terms of complexity or any other
|
|
tradeoffs involved)? Are there better solutions?
|
|
|
|
If the design is not yet clear (which is true of most features), then
|
|
the design is likely to benefit from more work and community input.
|
|
Make a list of issues, or write documentation including rationales for
|
|
how one would use the feature. Discuss it with coworkers, a
|
|
newsgroup, or a mailing list, and see what other people think.
|
|
Distribute some experimental patches and see what people think. The
|
|
intention is arrive at some kind of rough community consensus before
|
|
changing the "official" CVS. Features like zlib, encryption, and
|
|
the RCS library have benefitted from this process in the past.
|
|
|
|
If longstanding CVS behavior, that people may be relying on, is
|
|
clearly deficient, it can be changed, but only slowly and carefully.
|
|
For example, the global -q option was introduced in CVS 1.3 but the
|
|
command -q options, which the global -q replaced, were not removed
|
|
until CVS 1.6.
|
|
|
|
* Writing patches (tactics)
|
|
|
|
When you first distribute a patch it may be suitable to just put forth
|
|
a rough patch, or even just an idea. But before the end of the
|
|
process the following should exist:
|
|
|
|
- ChangeLog entry (see the GNU coding standards for details).
|
|
|
|
- Changes to the NEWS file and cvs.texinfo, if the change is a
|
|
user-visible change worth mentioning.
|
|
|
|
- Somewhere, a description of what the patch fixes (often in
|
|
comments in the code, or maybe the ChangeLog or documentation).
|
|
|
|
- Most of the time, a test case (see TESTS). It can be quite
|
|
frustrating to fix a bug only to see it reappear later, and adding
|
|
the case to the testsuite, where feasible, solves this and other
|
|
problems. See the TESTS file for notes on writing new tests.
|
|
|
|
If you solve several unrelated problems, it is generally easier to
|
|
consider the desirability of the changes if there is a separate patch
|
|
for each issue. Use context diffs or unidiffs for patches.
|
|
|
|
Include words like "I grant permission to distribute this patch under
|
|
the terms of the GNU Public License" with your patch. By sending a
|
|
patch to bug-cvs@nongnu.org, you implicitly grant this permission.
|
|
|
|
Submitting a patch to bug-cvs is the way to reach the people who have
|
|
signed up to receive such submissions (including CVS developers), but
|
|
there may or may not be much (or any) response. If you want to pursue
|
|
the matter further, you are probably best off working with the larger
|
|
CVS community. Distribute your patch as widely as desired (mailing
|
|
lists, newsgroups, web sites, whatever). Write a web page or other
|
|
information describing what the patch is for. It is neither practical
|
|
nor desirable for all/most contributions to be distributed through the
|
|
"official" (whatever that means) mechanisms of CVS releases and CVS
|
|
developers. Now, the "official" mechanisms do try to incorporate
|
|
those patches which seem most suitable for widespread usage, together
|
|
with test cases and documentation. So if a patch becomes sufficiently
|
|
popular in the CVS community, it is likely that one of the CVS
|
|
developers will eventually try to do something with it. But dealing
|
|
with the CVS developers may be the last step of the process rather
|
|
than the first.
|
|
|
|
* What is the schedule for the next release?
|
|
|
|
There isn't one. That is, upcoming releases are not announced (or
|
|
even hinted at, really) until the feature freeze which is
|
|
approximately 2 weeks before the final release (at this time test
|
|
releases start appearing and are announced on info-cvs). This is
|
|
intentional, to avoid a last minute rush to get new features in.
|
|
|
|
* Mailing lists
|
|
|
|
In addition to the mailing lists listed in the README file, developers should
|
|
take particular note of the following mailling lists:
|
|
|
|
bug-cvs: This is the list which users are requested to send bug reports
|
|
to. General CVS development and design discussions also take place on
|
|
this list.
|
|
info-cvs: This list is intended for user questions, but general CVS
|
|
development and design discussions sometimes take place on this list.
|
|
cvs-cvs: The only messages sent to this list are sent
|
|
automatically, via the CVS `loginfo' mechanism, when someone
|
|
checks something in to the master CVS repository.
|
|
cvs-test-results: The only messages sent to this list are sent
|
|
automatically, daily, by a script which runs "make check"
|
|
and "make remotecheck" on the master CVS sources.
|
|
|
|
To subscribe to any of these lists, send mail to <list>-request@nongnu.org
|
|
or visit http://savannah.nongnu.org/mail/?group=cvs and follow the instructions
|
|
for the list you wish to subscribe to.
|