Import (slightly modified) ru.koi8-r.win.kbd:1.1 from FreeBSD (fjoe):
[dragonfly.git] / contrib / cvs-1.12.11 / HACKING
1 How to write code for CVS
2
3 * Source
4
5 Patches against the development version of CVS are most likely to be accepted:
6
7         $ cvs -d:pserver:anoncvs@cvs.cvshome.org/cvsroot co ccvs
8
9 * Compiler options
10
11 If you are using GCC, you'll want to configure with -Wall, which can
12 detect many programming errors.  This is not the default because it
13 might cause spurious warnings, but at least on some machines, there
14 should be no spurious warnings.  For example:
15
16         $ ./configure CPPFLAGS=-Wall
17
18 * Backwards Compatibility
19
20 Only bug fixes are accepted into the stable branch.  New features should be
21 applied to the trunk.
22
23 If it is not inextricable from a bug fix, CVS's output (to stdout/stderr)
24 should not be changed on the stable branch in order to best support scripts and
25 other tools which parse CVS's output.  It is ok to change output between
26 feature releases (on the trunk), though such changes should be noted in the
27 NEWS file.
28
29 Changes in the way CVS responds to command line options, config options, etc.
30 should be accompanied by deprecation warnings for an entire stable series of
31 releases before being changed permanently, if at all possible.
32
33 * Indentation style
34
35 CVS mostly uses a consistent indentation style which looks like this:
36
37 void
38 foo (char *arg, int c)
39 {
40     long aflag;
41
42     if (arg != NULL)
43     {
44         bar (arg);
45         baz (arg);
46     }
47
48     switch (c)
49     {
50         case 'A':
51             aflag = 1;
52             break;
53     }
54
55     printf ("Literal string line 1\n"
56             "Literal string line 2\n"
57             "Literal string line 3\n");
58 }
59
60 The file cvs-format.el contains settings for emacs and the NEWS file
61 contains a set of options for the indent program which I haven't tried
62 but which are correct as far as I know.  You will find some code which
63 does not conform to this indentation style; the plan is to reindent it
64 as those sections of the code are changed (one function at a time,
65 perhaps).
66
67 In a submitted patch it is acceptable to refrain from changing the
68 indentation of large blocks of code to minimize the size of the patch;
69 the person checking in such a patch should reindent it.
70
71 * Portability
72
73 The general rule for portability is that it is only worth including
74 portability cruft for systems on which people are actually testing and
75 using new CVS releases.  Without testing, CVS will fail to be portable
76 for any number of unanticipated reasons.
77
78 CVS is now assuming a freestanding C89 compiler.  If you don't have one, you
79 should find an old release of GCC that did not require a freestanding C89
80 compiler to build, build that on your system, build a newer release of GCC
81 if you wish, then build CVS using GCC as your freestanding C89 compiler.
82
83 A freestanding C89 compiler is guaranteed to support function prototypes,
84 void *, and assert().
85
86 The following headers can be assumed and are included from lib/system.h for a
87 freestanding C89 implementation: <float.h>, <limits.h>, <stdarg.h>, <stddef.h>.
88 We are not assuming the other standard headers listed by C89 (hosted headers)
89 because these four headers are the only headers guaranteed to be shipped with
90 a C89 compiler (frestanding compiler).  We are not currently assuming that the
91 system the compiler is running on provides the rest of the C89 headers.
92
93 The following C89 hosted headers can be assumed due to their presence in UNIX
94 version 7 and are included from lib/system.h: <assert.h>, <ctype.h>, <errno.h>,
95 <math.h>, <setjmp.h>, <signal.h>, <stdio.h>.  <time.h> can also be assumed but
96 is included via lib/xtime.h via lib/system.h to include some Autoconf magic
97 which avoids including <time.h> and <sys/time.h> on systems that can't handle
98 both.
99
100 The following C89 headers are also assumed since we believe GCC includes them
101 even on systems where it is installed as a freestanding compiler when the
102 system lacks them, despite their not being required: <stdlib.h>, <string.h>.
103 When the system does not lack these headers, they can sometimes not be
104 standards compatible, but GCC provides a script, `fixincludes', for the purpose
105 of fixing ANSI conformance problems and we think we can rely on asking users to
106 either use GCC or run this script to fix conformance problems manually.  A
107 GNULIB developer has made a statement that if this turns out to be a problem,
108 GNULIB <stdlib.h> and <string.h> substitutes could be included in GNULIB, so if
109 we discover the problem, this should be discussed on <bug-gnulib@gnu.org>.
110
111 A substitute C99 <stdbool.h> is included from GNULIB for platforms that lack
112 this header.  Please see the comments in the lib/stdbool_.h file for its
113 limitations.
114
115 <sys/types.h> can be assumed despite a lack of a presence in even C99, since
116 it has been around nearly forever and noone has ever complained about our code
117 assuming its existance.
118
119 CVS has also been assuming <pwd.h> for some time.  I am unsure of the
120 rationale.
121
122 GNULIB also assumes <sys/stat.h>.  I am unsure of the rationale.
123
124 A substitute POSIX.2 <fnmatch.h> header and fnmatch() function is provided for
125 systems that lack them.  Similarly for the non-standard <alloca.h> header and
126 alloca() function.  Other substitute headers and functions are also provided
127 when needed.  See the lib directory or the srclist.txt file for more
128 information.
129
130 Please do not use multi-line strings.  Despite their common acceptance by many
131 compilers, they are not part of the ANSI C specification.  As of GCC version
132 3.3, they are no longer supported.  See the Indentation Style section above for
133 an example of a literal string which is not multi-line but which will print
134 multiple lines.
135
136 * Other style issues
137
138 When composing header files, do not declare function prototypes using the
139 `extern' storage-class identifier.  Under C89, there is no functional
140 difference between a function declaration with and without `extern', unless the 
141 function is declared `static'.  This is NOT the case for global variables.
142 Global variables declared in header files MUST be declared `extern'.  For
143 example:
144
145 /* Global variables */
146 extern int foo;
147 extern char *bar;
148
149 /* Function declarations */
150 int make_foo(void);
151 char *make_bar(int _foobar);
152
153 * Run-time behaviors
154
155 Use assert() to check "can't happen" conditions internal to CVS.  We
156 realize that there are functions in CVS which instead return NULL or
157 some such value (thus confusing the meaning of such a returned value),
158 but we want to fix that code.  Of course, bad input data, a corrupt
159 repository, bad options, etc., should always print a real error
160 message instead.
161
162 Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
163 operating system or some external interface requires it.  We spent a
164 lot of time getting rid of them, and we don't want to put them back.
165 If you find any that we missed, please report it as with other bugs.
166 In most cases such code will create security holes (for example, for
167 anonymous readonly access via the CVS protocol, or if a WWW cgi script
168 passes client-supplied arguments to CVS).
169
170 Although this is a long-term goal, it also would be nice to move CVS
171 in the direction of reentrancy.  This reduces the size of the data
172 segment and will allow a multi-threaded server if that is desirable.
173 It is also useful to write the code so that it can be easily be made
174 reentrant later.  For example, if you need to pass data to some functions,
175 you need a static variable, but use a single pointer so that when the function
176 is fixed to pass along the argument, then the code can easily use that
177 argument.
178
179 * Coding standards in general
180
181 Generally speaking the GNU coding standards are mostly used by CVS
182 (but see the exceptions mentioned above, such as indentation style,
183 and perhaps an exception or two we haven't mentioned).  This is the
184 file standards.text at the GNU FTP sites. The primary URL for this
185 information is http://www.gnu.org/prep/standards/ which contains links
186 to many different formats of the standards.
187
188 * Regenerating Build Files (UNIX)
189
190 On UNIX, if you wish to change the build files, you will need Autoconf and
191 Automake.
192
193 Some combinations of Automake and Autoconf versions may break the
194 CVS build if file timestamps aren't set correctly and people don't
195 have the same versions the developers do, so the rules to run them
196 automatically aren't included in the generated Makefiles unless you run
197 configure with --enable-maintainer-mode.
198
199 The CVS Makefiles and configure script were built using Automake 1.9.3 and
200 Autoconf 2.59, respectively.
201
202 There is a known bug in Autoconf 2.57 that will prevent the configure
203 scripts it generates from working on some platforms.  Other combinations of
204 autotool versions may or may not work.  If you get other versions to work,
205 please send a report to <bug-cvs@gnu.org>.
206
207 * Regenerating Build Files (Windows)
208
209 If for some reason you end up regenerating the *.mak files to submit a patch,
210 please run windows-NT/fix-msvc-mak.pl to remove the absolute paths from the
211 generated *.mak files before generating any patches.
212
213 * Writing patches (strategy)
214
215 Only some kinds of changes are suitable for inclusion in the
216 "official" CVS.  Bugfixes, where CVS's behavior contradicts the
217 documentation and/or expectations that everyone agrees on, should be
218 OK (strategically).  For features, the desirable attributes are that
219 the need is clear and that they fit nicely into the architecture of
220 CVS.  Is it worth the cost (in terms of complexity or any other
221 tradeoffs involved)?  Are there better solutions?
222
223 If the design is not yet clear (which is true of most features), then
224 the design is likely to benefit from more work and community input.
225 Make a list of issues, or write documentation including rationales for
226 how one would use the feature.  Discuss it with coworkers, a
227 newsgroup, or a mailing list, and see what other people think.
228 Distribute some experimental patches and see what people think.  The
229 intention is arrive at some kind of rough community consensus before
230 changing the "official" CVS.  Features like zlib, encryption, and
231 the RCS library have benefitted from this process in the past.
232
233 If longstanding CVS behavior, that people may be relying on, is
234 clearly deficient, it can be changed, but only slowly and carefully.
235 For example, the global -q option was introduced in CVS 1.3 but the
236 command -q options, which the global -q replaced, were not removed
237 until CVS 1.6.
238
239 * Writing patches (tactics)
240
241 When you first distribute a patch it may be suitable to just put forth
242 a rough patch, or even just an idea.  But before the end of the
243 process the following should exist:
244
245   - ChangeLog entry (see the GNU coding standards for details).
246
247   - Changes to the NEWS file and cvs.texinfo, if the change is a
248     user-visible change worth mentioning.
249
250   - Somewhere, a description of what the patch fixes (often in
251     comments in the code, or maybe the ChangeLog or documentation).
252
253   - Most of the time, a test case (see TESTS).  It can be quite
254     frustrating to fix a bug only to see it reappear later, and adding
255     the case to the testsuite, where feasible, solves this and other
256     problems.  See the TESTS file for notes on writing new tests.
257
258 If you solve several unrelated problems, it is generally easier to
259 consider the desirability of the changes if there is a separate patch
260 for each issue.  Use context diffs or unidiffs for patches.
261
262 Include words like "I grant permission to distribute this patch under
263 the terms of the GNU Public License" with your patch.  By sending a
264 patch to bug-cvs@gnu.org, you implicitly grant this permission.
265
266 Submitting a patch to bug-cvs is the way to reach the people who have
267 signed up to receive such submissions (including CVS developers), but
268 there may or may not be much (or any) response.  If you want to pursue
269 the matter further, you are probably best off working with the larger
270 CVS community.  Distribute your patch as widely as desired (mailing
271 lists, newsgroups, web sites, whatever).  Write a web page or other
272 information describing what the patch is for.  It is neither practical
273 nor desirable for all/most contributions to be distributed through the
274 "official" (whatever that means) mechanisms of CVS releases and CVS
275 developers.  Now, the "official" mechanisms do try to incorporate
276 those patches which seem most suitable for widespread usage, together
277 with test cases and documentation.  So if a patch becomes sufficiently
278 popular in the CVS community, it is likely that one of the CVS
279 developers will eventually try to do something with it.  But dealing
280 with the CVS developers may be the last step of the process rather
281 than the first.
282
283 * What is the schedule for the next release?
284
285 There isn't one.  That is, upcoming releases are not announced (or
286 even hinted at, really) until the feature freeze which is
287 approximately 2 weeks before the final release (at this time test
288 releases start appearing and are announced on info-cvs).  This is
289 intentional, to avoid a last minute rush to get new features in.
290
291 * Mailing lists
292
293 Anyone can add themselves to the following mailing lists:
294
295     dev.  Unless you are accepted as a CVS developer as
296       described in the DEVEL-CVS file, you will only be able to
297       read this list, not send to it.  The charter of the list is
298       also in DEVEL-CVS.
299     cvs.  The only messages sent to this list are sent
300       automatically, via the CVS `loginfo' mechanism, when someone
301       checks something in to the master CVS repository.
302     test-results.  The only messages sent to this list are sent
303       automatically, daily, by a script which runs "make check"
304       and "make remotecheck" on the master CVS sources.
305
306 To subscribe to dev, cvs, or test-results, send
307 a message to "<list>-subscribe@ccvs.cvshome.org" or visit
308 http://ccvs.cvshome.org/servlets/ProjectMailingListList and follow the
309 instructions there.
310
311 One other list related to CVS development is bug-cvs.  This is the
312 list which users are requested to send bug reports to.  Anyone can
313 subscribe; to do so send mail to bug-cvs-request@gnu.org.
314
315 Other CVS discussions take place on the info-cvs mailing list
316 (send mail to info-cvs-request@gnu.org to subscribe) or on
317 the newsgroup comp.software.config-mgmt.