1How to write code for CVS 2 3* Compiler options 4 5If you are using GCC, you'll want to configure with -Wall, which can 6detect many programming errors. This is not the default because it 7might cause spurious warnings, but at least on some machines, there 8should be no spurious warnings. For example: 9 10 $ CFLAGS="-g -Wall" ./configure 11 12Configure is not very good at remembering this setting; it will get 13wiped out whenever you do a ./config.status --recheck, so you'll need 14to use: 15 16 $ CFLAGS="-g -Wall" ./config.status --recheck 17 18* Indentation style 19 20CVS mostly uses a consistent indentation style which looks like this: 21 22void 23foo (arg) 24 char *arg; 25{ 26 if (arg != NULL) 27 { 28 bar (arg); 29 baz (arg); 30 } 31 switch (c) 32 { 33 case 'A': 34 aflag = 1; 35 break; 36 } 37} 38 39The file cvs-format.el contains settings for emacs and the NEWS file 40contains a set of options for the indent program which I haven't tried 41but which are correct as far as I know. You will find some code which 42does not conform to this indentation style; the plan is to reindent it 43as those sections of the code are changed (one function at a time, 44perhaps). 45 46In a submitted patch it is acceptable to refrain from changing the 47indentation of large blocks of code to minimize the size of the patch; 48the person checking in such a patch should reindent it. 49 50* Portability 51 52The general rule for portability is that it is only worth including 53portability cruft for systems on which people are actually testing and 54using new CVS releases. Without testing, CVS will fail to be portable 55for any number of unanticipated reasons. 56 57The current consequence of that general rule seems to be that if it 58is in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK 59to use it without ifdefs (for example, assert() and void * as long as 60you add more casts to and from void * than ANSI requires. But not 61function prototypes). Such constructs are generally portable enough, 62including to NT, OS/2, VMS, etc. 63 64* Run-time behaviors 65 66Use assert() to check "can't happen" conditions internal to CVS. We 67realize that there are functions in CVS which instead return NULL or 68some such value (thus confusing the meaning of such a returned value), 69but we want to fix that code. Of course, bad input data, a corrupt 70repository, bad options, etc., should always print a real error 71message instead. 72 73Do not use arbitrary limits (such as PATH_MAX) except perhaps when the 74operating system or some external interface requires it. We spent a 75lot of time getting rid of them, and we don't want to put them back. 76If you find any that we missed, please report it as with other bugs. 77In most cases such code will create security holes (for example, for 78anonymous readonly access via the CVS protocol, or if a WWW cgi script 79passes client-supplied arguments to CVS). 80 81Although this is a long-term goal, it also would be nice to move CVS 82in the direction of reentrancy. This reduces the size of the data 83segment and will allow a multi-threaded server if that is desirable. 84It is also useful to write the code so that it can be easily be made 85reentrant later. For example, if you need to pass data from a 86Parse_Info caller to its callproc, you need a static variable. But 87use a single pointer so that when Parse_Info is fixed to pass along a 88void * argument, then the code can easily use that argument. 89 90* Coding standards in general 91 92Generally speaking the GNU coding standards are mostly used by CVS 93(but see the exceptions mentioned above, such as indentation style, 94and perhaps an exception or two we haven't mentioned). This is the 95file standards.text at the GNU FTP sites. 96 97Filenames for .c and .h files may contain _ but should not contain - 98(the latter causes Visual C++ 2.1 to create makefiles which Visual C++ 994.0 cannot use). 100 101* Writing patches (strategy) 102 103Only some kinds of changes are suitable for inclusion in the 104"official" CVS. Bugfixes, where CVS's behavior contradicts the 105documentation and/or expectations that everyone agrees on, should be 106OK (strategically). For features, the desirable attributes are that 107the need is clear and that they fit nicely into the architecture of 108CVS. Is it worth the cost (in terms of complexity or any other 109tradeoffs involved)? Are there better solutions? 110 111If the design is not yet clear (which is true of most features), then 112the design is likely to benefit from more work and community input. 113Make a list of issues, or write documentation including rationales for 114how one would use the feature. Discuss it with coworkers, a 115newsgroup, or a mailing list, and see what other people think. 116Distribute some experimental patches and see what people think. The 117intention is arrive at some kind of rough community consensus before 118changing the "official" CVS. Features like zlib, encryption, and 119the RCS library have benefitted from this process in the past. 120 121If longstanding CVS behavior, that people may be relying on, is 122clearly deficient, it can be changed, but only slowly and carefully. 123For example, the global -q option was introduced in CVS 1.3 but the 124command -q options, which the global -q replaced, were not removed 125until CVS 1.6. 126 127* Writing patches (tactics) 128 129When you first distribute a patch it may be suitable to just put forth 130a rough patch, or even just an idea. But before the end of the 131process the following should exist: 132 133 - ChangeLog entry (see the GNU coding standards for details). 134 135 - Changes to the NEWS file and cvs.texinfo, if the change is a 136 user-visible change worth mentioning. 137 138 - Somewhere, a description of what the patch fixes (often in 139 comments in the code, or maybe the ChangeLog or documentation). 140 141 - Most of the time, a test case (see TESTS). It can be quite 142 frustrating to fix a bug only to see it reappear later, and adding 143 the case to the testsuite, where feasible, solves this and other 144 problems. 145 146If you solve several unrelated problems, it is generally easier to 147consider the desirability of the changes if there is a separate patch 148for each issue. Use context diffs or unidiffs for patches. 149 150Include words like "I grant permission to distribute this patch under 151the terms of the GNU Public License" with your patch. By sending a 152patch to bug-cvs@gnu.org, you implicitly grant this permission. 153 154Submitting a patch to bug-cvs is the way to reach the people who have 155signed up to receive such submissions (including CVS developers), but 156there may or may not be much (or any) response. If you want to pursue 157the matter further, you are probably best off working with the larger 158CVS community. Distribute your patch as widely as desired (mailing 159lists, newsgroups, web sites, whatever). Write a web page or other 160information describing what the patch is for. It is neither practical 161nor desirable for all/most contributions to be distributed through the 162"official" (whatever that means) mechanisms of CVS releases and CVS 163developers. Now, the "official" mechanisms do try to incorporate 164those patches which seem most suitable for widespread usage, together 165with test cases and documentation. So if a patch becomes sufficiently 166popular in the CVS community, it is likely that one of the CVS 167developers will eventually try to do something with it. But dealing 168with the CVS developers may be the last step of the process rather 169than the first. 170 171* What is the schedule for the next release? 172 173There isn't one. That is, upcoming releases are not announced (or 174even hinted at, really) until the feature freeze which is 175approximately 2 weeks before the final release (at this time test 176releases start appearing and are announced on info-cvs). This is 177intentional, to avoid a last minute rush to get new features in. 178 179* Mailing lists 180 181Anyone can add themselves to the following mailing lists: 182 183 devel-cvs. Unless you are accepted as a CVS developer as 184 described in the DEVEL-CVS file, you will only be able to 185 read this list, not send to it. The charter of the list is 186 also in DEVEL-CVS. 187 commit-cvs. The only messages sent to this list are sent 188 automatically, via the CVS `loginfo' mechanism, when someone 189 checks something in to the master CVS repository. 190 test-results. The only messages sent to this list are sent 191 automatically, daily, by a script which runs "make check" 192 and "make remotecheck" on the master CVS sources. 193To subscribe to devel-cvs, commit-cvs, or test-results, send 194a message to "majordomo@cvshome.org" whose body consists of 195"subscribe <list>", where <list> is devel-cvs, commit-cvs or 196test-results. 197 198One other list related to CVS development is bug-cvs. This is the 199list which users are requested to send bug reports to. Anyone can 200subscribe; to do so send mail to bug-cvs-request@gnu.org. 201 202Other CVS discussions take place on the info-cvs mailing list 203(send mail to info-cvs-request@gnu.org to subscribe) or on 204the newsgroup comp.software.config-mgmt. 205