117721SpeterHow to write code for CVS 217721Speter 3175261Sobrien* License of CVS 4175261Sobrien 5177391Sobrien CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc. 6175261Sobrien 7175261Sobrien This program is free software; you can redistribute it and/or modify 8175261Sobrien it under the terms of the GNU General Public License as published by 9175261Sobrien the Free Software Foundation; either version 1, or (at your option) 10175261Sobrien any later version. 11175261Sobrien 12175261Sobrien More details are available in the COPYING file but, in simplified 13175261Sobrien terms, this means that any distributed modifications you make to 14175261Sobrien this software must also be released under the GNU General Public 15175261Sobrien License. 16175261Sobrien 17175261Sobrien This program is distributed in the hope that it will be useful, 18175261Sobrien but WITHOUT ANY WARRANTY; without even the implied warranty of 19175261Sobrien MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20175261Sobrien GNU General Public License for more details. 21175261Sobrien 22102840Speter* Source 23102840Speter 24102840SpeterPatches against the development version of CVS are most likely to be accepted: 25102840Speter 26177391Sobrien $ cvs -z3 -d:pserver:anonymous@cvs.sv.nongnu.org:/sources/cvs co ccvs 27102840Speter 28177391SobrienSee the Savannah sources page <http://savannah.nongnu.org/cvs/?group=cvs> for 29177391Sobrienmore information. 30177391Sobrien 3117721Speter* Compiler options 3217721Speter 3317721SpeterIf you are using GCC, you'll want to configure with -Wall, which can 3417721Speterdetect many programming errors. This is not the default because it 3517721Spetermight cause spurious warnings, but at least on some machines, there 3617721Spetershould be no spurious warnings. For example: 3717721Speter 38175261Sobrien $ CFLAGS="-g -Wall" ./configure 3917721Speter 4017721SpeterConfigure is not very good at remembering this setting; it will get 4117721Speterwiped out whenever you do a ./config.status --recheck, so you'll need 4217721Speterto use: 4317721Speter 44175261Sobrien $ CFLAGS="-g -Wall" ./config.status --recheck 4517721Speter 46175261Sobrien* Backwards Compatibility 47175261Sobrien 48175261SobrienOnly bug fixes are accepted into the stable branch. New features should be 49175261Sobrienapplied to the trunk. 50175261Sobrien 51175261SobrienIf it is not inextricable from a bug fix, CVS's output (to stdout/stderr) 52175261Sobrienshould not be changed on the stable branch in order to best support scripts and 53175261Sobrienother tools which parse CVS's output. It is ok to change output between 54175261Sobrienfeature releases (on the trunk), though such changes should be noted in the 55175261SobrienNEWS file. 56175261Sobrien 57175261SobrienChanges in the way CVS responds to command line options, config options, etc. 58175261Sobrienshould be accompanied by deprecation warnings for an entire stable series of 59175261Sobrienreleases before being changed permanently, if at all possible. 60175261Sobrien 6117721Speter* Indentation style 6217721Speter 6317721SpeterCVS mostly uses a consistent indentation style which looks like this: 6417721Speter 6517721Spetervoid 6617721Speterfoo (arg) 6717721Speter char *arg; 6817721Speter{ 6917721Speter if (arg != NULL) 7017721Speter { 7117721Speter bar (arg); 7217721Speter baz (arg); 7317721Speter } 7432785Speter switch (c) 7532785Speter { 7632785Speter case 'A': 7732785Speter aflag = 1; 7832785Speter break; 7932785Speter } 8017721Speter} 8117721Speter 8217721SpeterThe file cvs-format.el contains settings for emacs and the NEWS file 8317721Spetercontains a set of options for the indent program which I haven't tried 8417721Speterbut which are correct as far as I know. You will find some code which 8517721Speterdoes not conform to this indentation style; the plan is to reindent it 8617721Speteras those sections of the code are changed (one function at a time, 8717721Speterperhaps). 8817721Speter 8917721SpeterIn a submitted patch it is acceptable to refrain from changing the 9017721Speterindentation of large blocks of code to minimize the size of the patch; 9117721Speterthe person checking in such a patch should reindent it. 9217721Speter 9317721Speter* Portability 9417721Speter 9525839SpeterThe general rule for portability is that it is only worth including 9625839Speterportability cruft for systems on which people are actually testing and 9725839Speterusing new CVS releases. Without testing, CVS will fail to be portable 9825839Speterfor any number of unanticipated reasons. 9917721Speter 10025839SpeterThe current consequence of that general rule seems to be that if it 10125839Speteris in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK 10225839Speterto use it without ifdefs (for example, assert() and void * as long as 10325839Speteryou add more casts to and from void * than ANSI requires. But not 10425839Speterfunction prototypes). Such constructs are generally portable enough, 10525839Speterincluding to NT, OS/2, VMS, etc. 10625839Speter 10717721Speter* Run-time behaviors 10817721Speter 10917721SpeterUse assert() to check "can't happen" conditions internal to CVS. We 11017721Speterrealize that there are functions in CVS which instead return NULL or 11117721Spetersome such value (thus confusing the meaning of such a returned value), 11217721Speterbut we want to fix that code. Of course, bad input data, a corrupt 11317721Speterrepository, bad options, etc., should always print a real error 11417721Spetermessage instead. 11517721Speter 11632785SpeterDo not use arbitrary limits (such as PATH_MAX) except perhaps when the 11732785Speteroperating system or some external interface requires it. We spent a 11832785Speterlot of time getting rid of them, and we don't want to put them back. 11932785SpeterIf you find any that we missed, please report it as with other bugs. 12032785SpeterIn most cases such code will create security holes (for example, for 12132785Speteranonymous readonly access via the CVS protocol, or if a WWW cgi script 12232785Speterpasses client-supplied arguments to CVS). 12325839Speter 12425839SpeterAlthough this is a long-term goal, it also would be nice to move CVS 12525839Speterin the direction of reentrancy. This reduces the size of the data 12625839Spetersegment and will allow a multi-threaded server if that is desirable. 12725839SpeterIt is also useful to write the code so that it can be easily be made 12825839Speterreentrant later. For example, if you need to pass data from a 12925839SpeterParse_Info caller to its callproc, you need a static variable. But 13025839Speteruse a single pointer so that when Parse_Info is fixed to pass along a 13125839Spetervoid * argument, then the code can easily use that argument. 13225839Speter 13317721Speter* Coding standards in general 13417721Speter 13517721SpeterGenerally speaking the GNU coding standards are mostly used by CVS 13617721Speter(but see the exceptions mentioned above, such as indentation style, 13717721Speterand perhaps an exception or two we haven't mentioned). This is the 13817721Speterfile standards.text at the GNU FTP sites. 13917721Speter 140130303Speter* Regenerating Build Files 141130303Speter 142130303SpeterOn UNIX, if you wish to change the Build files, you will need Autoconf and 143130303SpeterAutomake. 144130303Speter 145130303SpeterSome combinations of Automake and Autoconf versions may break the 146130303SpeterCVS build if file timestamps aren't set correctly and people don't 147130303Speterhave the same versions the developers do, so the rules to run them 148130303Speterautomatically aren't included in the generated Makefiles unless you run 149130303Speterconfigure with the --enable-maintainer-mode option. 150130303Speter 151177391SobrienThe CVS Makefiles and configure script were built using Automake 1.10 and 152177391SobrienAutoconf 2.61, respectively. 153130303Speter 154130303SpeterThere is a known bug in Autoconf 2.57 that will prevent the configure 155130303Speterscripts it generates from working on some platforms. Other combinations of 156130303Speterautotool versions may or may not work. If you get other versions to work, 157175261Sobrienplease send a report to <bug-cvs@nongnu.org>. 158130303Speter 15954427Speter* Writing patches (strategy) 16025839Speter 16125839SpeterOnly some kinds of changes are suitable for inclusion in the 16225839Speter"official" CVS. Bugfixes, where CVS's behavior contradicts the 16325839Speterdocumentation and/or expectations that everyone agrees on, should be 16425839SpeterOK (strategically). For features, the desirable attributes are that 16525839Speterthe need is clear and that they fit nicely into the architecture of 16654427SpeterCVS. Is it worth the cost (in terms of complexity or any other 16754427Spetertradeoffs involved)? Are there better solutions? 16825839Speter 16954427SpeterIf the design is not yet clear (which is true of most features), then 17054427Speterthe design is likely to benefit from more work and community input. 17154427SpeterMake a list of issues, or write documentation including rationales for 17254427Speterhow one would use the feature. Discuss it with coworkers, a 17354427Speternewsgroup, or a mailing list, and see what other people think. 17454427SpeterDistribute some experimental patches and see what people think. The 17554427Speterintention is arrive at some kind of rough community consensus before 17654427Speterchanging the "official" CVS. Features like zlib, encryption, and 17754427Speterthe RCS library have benefitted from this process in the past. 17825839Speter 17925839SpeterIf longstanding CVS behavior, that people may be relying on, is 18025839Speterclearly deficient, it can be changed, but only slowly and carefully. 18125839SpeterFor example, the global -q option was introduced in CVS 1.3 but the 18225839Spetercommand -q options, which the global -q replaced, were not removed 18325839Speteruntil CVS 1.6. 18425839Speter 18554427Speter* Writing patches (tactics) 18625839Speter 18754427SpeterWhen you first distribute a patch it may be suitable to just put forth 18854427Spetera rough patch, or even just an idea. But before the end of the 18954427Speterprocess the following should exist: 19017721Speter 19154427Speter - ChangeLog entry (see the GNU coding standards for details). 19225839Speter 19354427Speter - Changes to the NEWS file and cvs.texinfo, if the change is a 19454427Speter user-visible change worth mentioning. 19517721Speter 19654427Speter - Somewhere, a description of what the patch fixes (often in 19754427Speter comments in the code, or maybe the ChangeLog or documentation). 19817721Speter 19954427Speter - Most of the time, a test case (see TESTS). It can be quite 20054427Speter frustrating to fix a bug only to see it reappear later, and adding 20154427Speter the case to the testsuite, where feasible, solves this and other 202102840Speter problems. See the TESTS file for notes on writing new tests. 20317721Speter 20454427SpeterIf you solve several unrelated problems, it is generally easier to 20554427Speterconsider the desirability of the changes if there is a separate patch 20654427Speterfor each issue. Use context diffs or unidiffs for patches. 20754427Speter 20854427SpeterInclude words like "I grant permission to distribute this patch under 20954427Speterthe terms of the GNU Public License" with your patch. By sending a 210175261Sobrienpatch to bug-cvs@nongnu.org, you implicitly grant this permission. 21154427Speter 21254427SpeterSubmitting a patch to bug-cvs is the way to reach the people who have 21354427Spetersigned up to receive such submissions (including CVS developers), but 21454427Speterthere may or may not be much (or any) response. If you want to pursue 21554427Speterthe matter further, you are probably best off working with the larger 21654427SpeterCVS community. Distribute your patch as widely as desired (mailing 21754427Speterlists, newsgroups, web sites, whatever). Write a web page or other 21854427Speterinformation describing what the patch is for. It is neither practical 21954427Speternor desirable for all/most contributions to be distributed through the 22054427Speter"official" (whatever that means) mechanisms of CVS releases and CVS 22154427Speterdevelopers. Now, the "official" mechanisms do try to incorporate 22254427Speterthose patches which seem most suitable for widespread usage, together 22354427Speterwith test cases and documentation. So if a patch becomes sufficiently 22454427Speterpopular in the CVS community, it is likely that one of the CVS 22554427Speterdevelopers will eventually try to do something with it. But dealing 22654427Speterwith the CVS developers may be the last step of the process rather 22754427Speterthan the first. 22854427Speter 22917721Speter* What is the schedule for the next release? 23017721Speter 23117721SpeterThere isn't one. That is, upcoming releases are not announced (or 23217721Spetereven hinted at, really) until the feature freeze which is 23317721Speterapproximately 2 weeks before the final release (at this time test 23417721Speterreleases start appearing and are announced on info-cvs). This is 23517721Speterintentional, to avoid a last minute rush to get new features in. 23625839Speter 23725839Speter* Mailing lists 23825839Speter 239175261SobrienIn addition to the mailing lists listed in the README file, developers should 240175261Sobrientake particular note of the following mailling lists: 24125839Speter 242175261Sobrien bug-cvs: This is the list which users are requested to send bug reports 243175261Sobrien to. General CVS development and design discussions also take place on 244175261Sobrien this list. 245175261Sobrien info-cvs: This list is intended for user questions, but general CVS 246175261Sobrien development and design discussions sometimes take place on this list. 247175261Sobrien cvs-cvs: The only messages sent to this list are sent 24825839Speter automatically, via the CVS `loginfo' mechanism, when someone 24925839Speter checks something in to the master CVS repository. 250175261Sobrien cvs-test-results: The only messages sent to this list are sent 25125839Speter automatically, daily, by a script which runs "make check" 25225839Speter and "make remotecheck" on the master CVS sources. 25325839Speter 254175261SobrienTo subscribe to any of these lists, send mail to <list>-request@nongnu.org 255175261Sobrienor visit http://savannah.nongnu.org/mail/?group=cvs and follow the instructions 256175261Sobrienfor the list you wish to subscribe to. 257