1 How to write code for CVS
5 CVS is Copyright (C) 1989-2005 The Free Software Foundation, Inc.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 1, or (at your option)
12 More details are available in the COPYING file but, in simplified
13 terms, this means that any distributed modifications you make to
14 this software must also be released under the GNU General Public
17 This program is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 GNU General Public License for more details.
24 Patches against the development version of CVS are most likely to be accepted:
26 $ CVS_RSH=ssh cvs -d:ext:anoncvs@savannah.nongnu.org:/cvsroot/cvs co ccvs
30 If you are using GCC, you'll want to configure with -Wall, which can
31 detect many programming errors. This is not the default because it
32 might cause spurious warnings, but at least on some machines, there
33 should be no spurious warnings. For example:
35 $ CFLAGS="-g -Wall" ./configure
37 Configure is not very good at remembering this setting; it will get
38 wiped out whenever you do a ./config.status --recheck, so you'll need
41 $ CFLAGS="-g -Wall" ./config.status --recheck
43 * Backwards Compatibility
45 Only bug fixes are accepted into the stable branch. New features should be
48 If it is not inextricable from a bug fix, CVS's output (to stdout/stderr)
49 should not be changed on the stable branch in order to best support scripts and
50 other tools which parse CVS's output. It is ok to change output between
51 feature releases (on the trunk), though such changes should be noted in the
54 Changes in the way CVS responds to command line options, config options, etc.
55 should be accompanied by deprecation warnings for an entire stable series of
56 releases before being changed permanently, if at all possible.
60 CVS mostly uses a consistent indentation style which looks like this:
79 The file cvs-format.el contains settings for emacs and the NEWS file
80 contains a set of options for the indent program which I haven't tried
81 but which are correct as far as I know. You will find some code which
82 does not conform to this indentation style; the plan is to reindent it
83 as those sections of the code are changed (one function at a time,
86 In a submitted patch it is acceptable to refrain from changing the
87 indentation of large blocks of code to minimize the size of the patch;
88 the person checking in such a patch should reindent it.
92 The general rule for portability is that it is only worth including
93 portability cruft for systems on which people are actually testing and
94 using new CVS releases. Without testing, CVS will fail to be portable
95 for any number of unanticipated reasons.
97 The current consequence of that general rule seems to be that if it
98 is in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK
99 to use it without ifdefs (for example, assert() and void * as long as
100 you add more casts to and from void * than ANSI requires. But not
101 function prototypes). Such constructs are generally portable enough,
102 including to NT, OS/2, VMS, etc.
106 Use assert() to check "can't happen" conditions internal to CVS. We
107 realize that there are functions in CVS which instead return NULL or
108 some such value (thus confusing the meaning of such a returned value),
109 but we want to fix that code. Of course, bad input data, a corrupt
110 repository, bad options, etc., should always print a real error
113 Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
114 operating system or some external interface requires it. We spent a
115 lot of time getting rid of them, and we don't want to put them back.
116 If you find any that we missed, please report it as with other bugs.
117 In most cases such code will create security holes (for example, for
118 anonymous readonly access via the CVS protocol, or if a WWW cgi script
119 passes client-supplied arguments to CVS).
121 Although this is a long-term goal, it also would be nice to move CVS
122 in the direction of reentrancy. This reduces the size of the data
123 segment and will allow a multi-threaded server if that is desirable.
124 It is also useful to write the code so that it can be easily be made
125 reentrant later. For example, if you need to pass data from a
126 Parse_Info caller to its callproc, you need a static variable. But
127 use a single pointer so that when Parse_Info is fixed to pass along a
128 void * argument, then the code can easily use that argument.
130 * Coding standards in general
132 Generally speaking the GNU coding standards are mostly used by CVS
133 (but see the exceptions mentioned above, such as indentation style,
134 and perhaps an exception or two we haven't mentioned). This is the
135 file standards.text at the GNU FTP sites.
137 * Regenerating Build Files
139 On UNIX, if you wish to change the Build files, you will need Autoconf and
142 Some combinations of Automake and Autoconf versions may break the
143 CVS build if file timestamps aren't set correctly and people don't
144 have the same versions the developers do, so the rules to run them
145 automatically aren't included in the generated Makefiles unless you run
146 configure with the --enable-maintainer-mode option.
148 The CVS Makefiles and configure script were built using Automake 1.9.6 and
149 Autoconf 2.59, respectively.
151 There is a known bug in Autoconf 2.57 that will prevent the configure
152 scripts it generates from working on some platforms. Other combinations of
153 autotool versions may or may not work. If you get other versions to work,
154 please send a report to <bug-cvs@nongnu.org>.
156 * Writing patches (strategy)
158 Only some kinds of changes are suitable for inclusion in the
159 "official" CVS. Bugfixes, where CVS's behavior contradicts the
160 documentation and/or expectations that everyone agrees on, should be
161 OK (strategically). For features, the desirable attributes are that
162 the need is clear and that they fit nicely into the architecture of
163 CVS. Is it worth the cost (in terms of complexity or any other
164 tradeoffs involved)? Are there better solutions?
166 If the design is not yet clear (which is true of most features), then
167 the design is likely to benefit from more work and community input.
168 Make a list of issues, or write documentation including rationales for
169 how one would use the feature. Discuss it with coworkers, a
170 newsgroup, or a mailing list, and see what other people think.
171 Distribute some experimental patches and see what people think. The
172 intention is arrive at some kind of rough community consensus before
173 changing the "official" CVS. Features like zlib, encryption, and
174 the RCS library have benefitted from this process in the past.
176 If longstanding CVS behavior, that people may be relying on, is
177 clearly deficient, it can be changed, but only slowly and carefully.
178 For example, the global -q option was introduced in CVS 1.3 but the
179 command -q options, which the global -q replaced, were not removed
182 * Writing patches (tactics)
184 When you first distribute a patch it may be suitable to just put forth
185 a rough patch, or even just an idea. But before the end of the
186 process the following should exist:
188 - ChangeLog entry (see the GNU coding standards for details).
190 - Changes to the NEWS file and cvs.texinfo, if the change is a
191 user-visible change worth mentioning.
193 - Somewhere, a description of what the patch fixes (often in
194 comments in the code, or maybe the ChangeLog or documentation).
196 - Most of the time, a test case (see TESTS). It can be quite
197 frustrating to fix a bug only to see it reappear later, and adding
198 the case to the testsuite, where feasible, solves this and other
199 problems. See the TESTS file for notes on writing new tests.
201 If you solve several unrelated problems, it is generally easier to
202 consider the desirability of the changes if there is a separate patch
203 for each issue. Use context diffs or unidiffs for patches.
205 Include words like "I grant permission to distribute this patch under
206 the terms of the GNU Public License" with your patch. By sending a
207 patch to bug-cvs@nongnu.org, you implicitly grant this permission.
209 Submitting a patch to bug-cvs is the way to reach the people who have
210 signed up to receive such submissions (including CVS developers), but
211 there may or may not be much (or any) response. If you want to pursue
212 the matter further, you are probably best off working with the larger
213 CVS community. Distribute your patch as widely as desired (mailing
214 lists, newsgroups, web sites, whatever). Write a web page or other
215 information describing what the patch is for. It is neither practical
216 nor desirable for all/most contributions to be distributed through the
217 "official" (whatever that means) mechanisms of CVS releases and CVS
218 developers. Now, the "official" mechanisms do try to incorporate
219 those patches which seem most suitable for widespread usage, together
220 with test cases and documentation. So if a patch becomes sufficiently
221 popular in the CVS community, it is likely that one of the CVS
222 developers will eventually try to do something with it. But dealing
223 with the CVS developers may be the last step of the process rather
226 * What is the schedule for the next release?
228 There isn't one. That is, upcoming releases are not announced (or
229 even hinted at, really) until the feature freeze which is
230 approximately 2 weeks before the final release (at this time test
231 releases start appearing and are announced on info-cvs). This is
232 intentional, to avoid a last minute rush to get new features in.
236 In addition to the mailing lists listed in the README file, developers should
237 take particular note of the following mailling lists:
239 bug-cvs: This is the list which users are requested to send bug reports
240 to. General CVS development and design discussions also take place on
242 info-cvs: This list is intended for user questions, but general CVS
243 development and design discussions sometimes take place on this list.
244 cvs-cvs: The only messages sent to this list are sent
245 automatically, via the CVS `loginfo' mechanism, when someone
246 checks something in to the master CVS repository.
247 cvs-test-results: The only messages sent to this list are sent
248 automatically, daily, by a script which runs "make check"
249 and "make remotecheck" on the master CVS sources.
251 To subscribe to any of these lists, send mail to <list>-request@nongnu.org
252 or visit http://savannah.nongnu.org/mail/?group=cvs and follow the instructions
253 for the list you wish to subscribe to.