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