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