/contrib/cvs/HACKING

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