contrib/cvs/HACKING

   1 How to write code for CVS
   2
   3 * Compiler options
   4
   5 If you are using GCC, you'll want to configure with -Wall, which can
   6 detect many programming errors.  This is not the default because it
   7 might cause spurious warnings, but at least on some machines, there
   8 should be no spurious warnings.  For example:
   9
  10         $ CFLAGS="-g -Wall" ./configure
  11
  12 Configure is not very good at remembering this setting; it will get
  13 wiped out whenever you do a ./config.status --recheck, so you'll need
  14 to use:
  15
  16         $ CFLAGS="-g -Wall" ./config.status --recheck
  17
  18 * Indentation style
  19
  20 CVS mostly uses a consistent indentation style which looks like this:
  21
  22 void
  23 foo (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
  39 The file cvs-format.el contains settings for emacs and the NEWS file
  40 contains a set of options for the indent program which I haven't tried
  41 but which are correct as far as I know.  You will find some code which
  42 does not conform to this indentation style; the plan is to reindent it
  43 as those sections of the code are changed (one function at a time,
  44 perhaps).
  45
  46 In a submitted patch it is acceptable to refrain from changing the
  47 indentation of large blocks of code to minimize the size of the patch;
  48 the person checking in such a patch should reindent it.
  49
  50 * Portability
  51
  52 The general rule for portability is that it is only worth including
  53 portability cruft for systems on which people are actually testing and
  54 using new CVS releases.  Without testing, CVS will fail to be portable
  55 for any number of unanticipated reasons.
  56
  57 The current consequence of that general rule seems to be that if it
  58 is in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK
  59 to use it without ifdefs (for example, assert() and void * as long as
  60 you add more casts to and from void * than ANSI requires.  But not
  61 function prototypes).  Such constructs are generally portable enough,
  62 including to NT, OS/2, VMS, etc.
  63
  64 * Run-time behaviors
  65
  66 Use assert() to check "can't happen" conditions internal to CVS.  We
  67 realize that there are functions in CVS which instead return NULL or
  68 some such value (thus confusing the meaning of such a returned value),
  69 but we want to fix that code.  Of course, bad input data, a corrupt
  70 repository, bad options, etc., should always print a real error
  71 message instead.
  72
  73 Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
  74 operating system or some external interface requires it.  We spent a
  75 lot of time getting rid of them, and we don't want to put them back.
  76 If you find any that we missed, please report it as with other bugs.
  77 In most cases such code will create security holes (for example, for
  78 anonymous readonly access via the CVS protocol, or if a WWW cgi script
  79 passes client-supplied arguments to CVS).
  80
  81 Although this is a long-term goal, it also would be nice to move CVS
  82 in the direction of reentrancy.  This reduces the size of the data
  83 segment and will allow a multi-threaded server if that is desirable.
  84 It is also useful to write the code so that it can be easily be made
  85 reentrant later.  For example, if you need to pass data from a
  86 Parse_Info caller to its callproc, you need a static variable.  But
  87 use a single pointer so that when Parse_Info is fixed to pass along a
  88 void * argument, then the code can easily use that argument.
  89
  90 * Coding standards in general
  91
  92 Generally speaking the GNU coding standards are mostly used by CVS
  93 (but see the exceptions mentioned above, such as indentation style,
  94 and perhaps an exception or two we haven't mentioned).  This is the
  95 file standards.text at the GNU FTP sites.
  96
  97 Filenames 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++
  99 4.0 cannot use).
 100
 101 * Submitting patches (strategy)
 102
 103 Only some kinds of changes are suitable for inclusion in the
 104 "official" CVS.  Bugfixes, where CVS's behavior contradicts the
 105 documentation and/or expectations that everyone agrees on, should be
 106 OK (strategically).  For features, the desirable attributes are that
 107 the need is clear and that they fit nicely into the architecture of
 108 CVS.
 109
 110 However, if there is reason to think that a change would significantly
 111 inconvenience any significant body of CVS users, or would be
 112 controversial for other reasons, then the design should be re-thought.
 113 Go back to the requirements (writing documentation might help, if you
 114 write the documentation to explain why one would use the feature not
 115 just what the feature does).  Think about whether there is a behavior
 116 which works in both your situation and the other situations.  Make a
 117 list of the issues (for example, submit a comment or documentation
 118 change).  Ask your coworkers, a newsgroup, or a mailing list, and see
 119 what other people think.  Distribute some experimental patches outside
 120 the "official" CVS and see what people think.  By this process, the
 121 intention is that once-controversial changes can be refined to the
 122 point where they are relatively uncontroversial before they are
 123 actually checked in to the "official" CVS.  Features like zlib,
 124 encryption, and others have benefitted from this process in the past
 125 by being mentioned in the documentation and/or discussed, before an
 126 implementation was checked in.
 127
 128 If longstanding CVS behavior, that people may be relying on, is
 129 clearly deficient, it can be changed, but only slowly and carefully.
 130 For example, the global -q option was introduced in CVS 1.3 but the
 131 command -q options, which the global -q replaced, were not removed
 132 until CVS 1.6.
 133
 134 * Submitting patches (tactics)
 135
 136 Please include a ChangeLog entry (see the GNU coding standards for
 137 information on writing one) with patches.  Include a description of
 138 what the patch does (sometimes the ChangeLog entry and/or comments in
 139 the code are appropriate for this, but not always)--patches should not
 140 be checked in unless there is some reason for them, and the
 141 description may be helpful if there is a better way to solve the
 142 problem.  In addition to the ChangeLog entry, there should be a change
 143 to the NEWS file and cvs.texinfo, if the change is a user-visible
 144 change worth mentioning.
 145
 146 It is nice to have a test case (see TESTS), especially for fixes which
 147 involve subtle behaviors or twisted sections of the code.
 148
 149 If you solve several unrelated problems, submit a separate
 150 patch for each one.  Patches should be tested before submission.  Use
 151 context diffs or unidiffs for patches.
 152
 153 Note that all submitted changes may be distributed under the terms of
 154 the GNU Public License, so if you don't like this, don't submit them.
 155 Submit changes to bug-cvs@gnu.org.
 156
 157 Generally speaking if you follow the guidelines in this file you can
 158 expect a yes or no answer about whether your patch is accepted.  But
 159 even in this case there is no guarantee because wading through a bunch
 160 of submissions can be time consuming, and noone has volunteered to
 161 offer any such guarantee.  If you don't receive an answer one way or
 162 another within a month, feel free to ask what the status is.  You can,
 163 if you wish, distribute your patch on mailing lists or newsgroups, if
 164 you want to make it available before it gets merged.
 165
 166 * What is the schedule for the next release?
 167
 168 There isn't one.  That is, upcoming releases are not announced (or
 169 even hinted at, really) until the feature freeze which is
 170 approximately 2 weeks before the final release (at this time test
 171 releases start appearing and are announced on info-cvs).  This is
 172 intentional, to avoid a last minute rush to get new features in.
 173
 174 * Mailing lists
 175
 176 Anyone can add themselves to the following mailing lists:
 177
 178     devel-cvs.  Unless you are accepted as a CVS developer as
 179       described in the DEVEL-CVS file, you will only be able to
 180       read this list, not send to it.  The charter of the list is
 181       also in DEVEL-CVS.
 182     commit-cvs.  The only messages sent to this list are sent
 183       automatically, via the CVS `loginfo' mechanism, when someone
 184       checks something in to the master CVS repository.
 185     test-results.  The only messages sent to this list are sent
 186       automatically, daily, by a script which runs "make check"
 187       and "make remotecheck" on the master CVS sources.
 188 To subscribe to devel-cvs, commit-cvs, or test-results, send
 189 a message to "majordomo@cyclic.com" whose body consists of
 190 "subscribe <list>", where <list> is devel-cvs, commit-cvs or
 191 test-results.
 192
 193 One other list related to CVS development is bug-cvs.  This is the
 194 list which users are requested to send bug reports to.  Anyone can
 195 subscribe; to do so send mail to bug-cvs-request@gnu.org.
 196
 197 Other CVS discussions take place on the info-cvs mailing list
 198 (send mail to info-cvs-request@prep.ai.mit.edu to subscribe) or on
 199 the newsgroup comp.software.config-mgmt.