732631db68
things fixed in here, including the '-ko' vs. -A problem with remote cvs which caused all files with -ko to be resent each time (which is damn painful over a modem, I can tell you). It also found a heap of stray empty directories that should have been pruned with the -P flag to cvs update but were not for some reason. It also has the fully integrated rcs and diff, so no more fork/exec overheads for rcs,ci,patch,diff,etc. This means that it parses the control data in the rcs files only once rather than twice or more. If the 'cvs diff' vs. Index thing is going to be fixed for future patch compatability, this is the place to do it.
200 lines
8.6 KiB
Plaintext
200 lines
8.6 KiB
Plaintext
How to write code for CVS
|
|
|
|
* 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
|
|
|
|
* 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.
|
|
|
|
Filenames for .c and .h files may contain _ but should not contain -
|
|
(the latter causes Visual C++ 2.1 to create makefiles which Visual C++
|
|
4.0 cannot use).
|
|
|
|
* Submitting 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.
|
|
|
|
However, if there is reason to think that a change would significantly
|
|
inconvenience any significant body of CVS users, or would be
|
|
controversial for other reasons, then the design should be re-thought.
|
|
Go back to the requirements (writing documentation might help, if you
|
|
write the documentation to explain why one would use the feature not
|
|
just what the feature does). Think about whether there is a behavior
|
|
which works in both your situation and the other situations. Make a
|
|
list of the issues (for example, submit a comment or documentation
|
|
change). Ask your coworkers, a newsgroup, or a mailing list, and see
|
|
what other people think. Distribute some experimental patches outside
|
|
the "official" CVS and see what people think. By this process, the
|
|
intention is that once-controversial changes can be refined to the
|
|
point where they are relatively uncontroversial before they are
|
|
actually checked in to the "official" CVS. Features like zlib,
|
|
encryption, and others have benefitted from this process in the past
|
|
by being mentioned in the documentation and/or discussed, before an
|
|
implementation was checked in.
|
|
|
|
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.
|
|
|
|
* Submitting patches (tactics)
|
|
|
|
Please include a ChangeLog entry (see the GNU coding standards for
|
|
information on writing one) with patches. Include a description of
|
|
what the patch does (sometimes the ChangeLog entry and/or comments in
|
|
the code are appropriate for this, but not always)--patches should not
|
|
be checked in unless there is some reason for them, and the
|
|
description may be helpful if there is a better way to solve the
|
|
problem. In addition to the ChangeLog entry, there should be a change
|
|
to the NEWS file and cvs.texinfo, if the change is a user-visible
|
|
change worth mentioning.
|
|
|
|
It is nice to have a test case (see TESTS), especially for fixes which
|
|
involve subtle behaviors or twisted sections of the code.
|
|
|
|
If you solve several unrelated problems, submit a separate
|
|
patch for each one. Patches should be tested before submission. Use
|
|
context diffs or unidiffs for patches.
|
|
|
|
Note that all submitted changes may be distributed under the terms of
|
|
the GNU Public License, so if you don't like this, don't submit them.
|
|
Submit changes to bug-cvs@gnu.org.
|
|
|
|
Generally speaking if you follow the guidelines in this file you can
|
|
expect a yes or no answer about whether your patch is accepted. But
|
|
even in this case there is no guarantee because wading through a bunch
|
|
of submissions can be time consuming, and noone has volunteered to
|
|
offer any such guarantee. If you don't receive an answer one way or
|
|
another within a month, feel free to ask what the status is. You can,
|
|
if you wish, distribute your patch on mailing lists or newsgroups, if
|
|
you want to make it available before it gets merged.
|
|
|
|
* 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
|
|
|
|
Anyone can add themselves to the following mailing lists:
|
|
|
|
devel-cvs. Unless you are accepted as a CVS developer as
|
|
described in the DEVEL-CVS file, you will only be able to
|
|
read this list, not send to it. The charter of the list is
|
|
also in DEVEL-CVS.
|
|
commit-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.
|
|
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 devel-cvs, commit-cvs, or test-results, send
|
|
a message to "majordomo@cyclic.com" whose body consists of
|
|
"subscribe <list>", where <list> is devel-cvs, commit-cvs or
|
|
test-results.
|
|
|
|
One other list related to CVS development is bug-cvs. This is the
|
|
list which users are requested to send bug reports to. Anyone can
|
|
subscribe; to do so send mail to bug-cvs-request@gnu.org.
|
|
|
|
Other CVS discussions take place on the info-cvs mailing list
|
|
(send mail to info-cvs-request@prep.ai.mit.edu to subscribe) or on
|
|
the newsgroup comp.software.config-mgmt.
|