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