contrib/cvs/HACKING

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