diff options
Diffstat (limited to 'contrib/cvs/HACKING')
| -rw-r--r-- | contrib/cvs/HACKING | 256 |
1 files changed, 0 insertions, 256 deletions
diff --git a/contrib/cvs/HACKING b/contrib/cvs/HACKING deleted file mode 100644 index c71d307..0000000 --- a/contrib/cvs/HACKING +++ /dev/null @@ -1,256 +0,0 @@ -How to write code for CVS - -* License of CVS - - CVS is Copyright (C) 1986-2006 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 -z3 -d:pserver:anonymous@cvs.sv.nongnu.org:/sources/cvs co ccvs - -See the Savannah sources page <http://savannah.nongnu.org/cvs/?group=cvs> for -more information. - -* 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.10 and -Autoconf 2.61, 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. |
