/contrib/cvs/HACKING

https://bitbucket.org/freebsd/freebsd-head/ · #! · 256 lines · 200 code · 56 blank · 0 comment · 0 complexity · 6fdd9e098e2f7c31a4e164acee246c32 MD5 · raw file

  1. How to write code for CVS
  2. * License of CVS
  3. CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc.
  4. This program is free software; you can redistribute it and/or modify
  5. it under the terms of the GNU General Public License as published by
  6. the Free Software Foundation; either version 1, or (at your option)
  7. any later version.
  8. More details are available in the COPYING file but, in simplified
  9. terms, this means that any distributed modifications you make to
  10. this software must also be released under the GNU General Public
  11. License.
  12. This program is distributed in the hope that it will be useful,
  13. but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. GNU General Public License for more details.
  16. * Source
  17. Patches against the development version of CVS are most likely to be accepted:
  18. $ cvs -z3 -d:pserver:anonymous@cvs.sv.nongnu.org:/sources/cvs co ccvs
  19. See the Savannah sources page <http://savannah.nongnu.org/cvs/?group=cvs> for
  20. more information.
  21. * Compiler options
  22. If you are using GCC, you'll want to configure with -Wall, which can
  23. detect many programming errors. This is not the default because it
  24. might cause spurious warnings, but at least on some machines, there
  25. should be no spurious warnings. For example:
  26. $ CFLAGS="-g -Wall" ./configure
  27. Configure is not very good at remembering this setting; it will get
  28. wiped out whenever you do a ./config.status --recheck, so you'll need
  29. to use:
  30. $ CFLAGS="-g -Wall" ./config.status --recheck
  31. * Backwards Compatibility
  32. Only bug fixes are accepted into the stable branch. New features should be
  33. applied to the trunk.
  34. If it is not inextricable from a bug fix, CVS's output (to stdout/stderr)
  35. should not be changed on the stable branch in order to best support scripts and
  36. other tools which parse CVS's output. It is ok to change output between
  37. feature releases (on the trunk), though such changes should be noted in the
  38. NEWS file.
  39. Changes in the way CVS responds to command line options, config options, etc.
  40. should be accompanied by deprecation warnings for an entire stable series of
  41. releases before being changed permanently, if at all possible.
  42. * Indentation style
  43. CVS mostly uses a consistent indentation style which looks like this:
  44. void
  45. foo (arg)
  46. char *arg;
  47. {
  48. if (arg != NULL)
  49. {
  50. bar (arg);
  51. baz (arg);
  52. }
  53. switch (c)
  54. {
  55. case 'A':
  56. aflag = 1;
  57. break;
  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. In a submitted patch it is acceptable to refrain from changing the
  67. indentation of large blocks of code to minimize the size of the patch;
  68. the person checking in such a patch should reindent it.
  69. * Portability
  70. The general rule for portability is that it is only worth including
  71. portability cruft for systems on which people are actually testing and
  72. using new CVS releases. Without testing, CVS will fail to be portable
  73. for any number of unanticipated reasons.
  74. The current consequence of that general rule seems to be that if it
  75. is in ANSI C and it is in SunOS4 (using /bin/cc), generally it is OK
  76. to use it without ifdefs (for example, assert() and void * as long as
  77. you add more casts to and from void * than ANSI requires. But not
  78. function prototypes). Such constructs are generally portable enough,
  79. including to NT, OS/2, VMS, etc.
  80. * Run-time behaviors
  81. Use assert() to check "can't happen" conditions internal to CVS. We
  82. realize that there are functions in CVS which instead return NULL or
  83. some such value (thus confusing the meaning of such a returned value),
  84. but we want to fix that code. Of course, bad input data, a corrupt
  85. repository, bad options, etc., should always print a real error
  86. message instead.
  87. Do not use arbitrary limits (such as PATH_MAX) except perhaps when the
  88. operating system or some external interface requires it. We spent a
  89. lot of time getting rid of them, and we don't want to put them back.
  90. If you find any that we missed, please report it as with other bugs.
  91. In most cases such code will create security holes (for example, for
  92. anonymous readonly access via the CVS protocol, or if a WWW cgi script
  93. passes client-supplied arguments to CVS).
  94. Although this is a long-term goal, it also would be nice to move CVS
  95. in the direction of reentrancy. This reduces the size of the data
  96. segment and will allow a multi-threaded server if that is desirable.
  97. It is also useful to write the code so that it can be easily be made
  98. reentrant later. For example, if you need to pass data from a
  99. Parse_Info caller to its callproc, you need a static variable. But
  100. use a single pointer so that when Parse_Info is fixed to pass along a
  101. void * argument, then the code can easily use that argument.
  102. * Coding standards in general
  103. Generally speaking the GNU coding standards are mostly used by CVS
  104. (but see the exceptions mentioned above, such as indentation style,
  105. and perhaps an exception or two we haven't mentioned). This is the
  106. file standards.text at the GNU FTP sites.
  107. * Regenerating Build Files
  108. On UNIX, if you wish to change the Build files, you will need Autoconf and
  109. Automake.
  110. Some combinations of Automake and Autoconf versions may break the
  111. CVS build if file timestamps aren't set correctly and people don't
  112. have the same versions the developers do, so the rules to run them
  113. automatically aren't included in the generated Makefiles unless you run
  114. configure with the --enable-maintainer-mode option.
  115. The CVS Makefiles and configure script were built using Automake 1.10 and
  116. Autoconf 2.61, respectively.
  117. There is a known bug in Autoconf 2.57 that will prevent the configure
  118. scripts it generates from working on some platforms. Other combinations of
  119. autotool versions may or may not work. If you get other versions to work,
  120. please send a report to <bug-cvs@nongnu.org>.
  121. * Writing patches (strategy)
  122. Only some kinds of changes are suitable for inclusion in the
  123. "official" CVS. Bugfixes, where CVS's behavior contradicts the
  124. documentation and/or expectations that everyone agrees on, should be
  125. OK (strategically). For features, the desirable attributes are that
  126. the need is clear and that they fit nicely into the architecture of
  127. CVS. Is it worth the cost (in terms of complexity or any other
  128. tradeoffs involved)? Are there better solutions?
  129. If the design is not yet clear (which is true of most features), then
  130. the design is likely to benefit from more work and community input.
  131. Make a list of issues, or write documentation including rationales for
  132. how one would use the feature. Discuss it with coworkers, a
  133. newsgroup, or a mailing list, and see what other people think.
  134. Distribute some experimental patches and see what people think. The
  135. intention is arrive at some kind of rough community consensus before
  136. changing the "official" CVS. Features like zlib, encryption, and
  137. the RCS library have benefitted from this process in the past.
  138. If longstanding CVS behavior, that people may be relying on, is
  139. clearly deficient, it can be changed, but only slowly and carefully.
  140. For example, the global -q option was introduced in CVS 1.3 but the
  141. command -q options, which the global -q replaced, were not removed
  142. until CVS 1.6.
  143. * Writing patches (tactics)
  144. When you first distribute a patch it may be suitable to just put forth
  145. a rough patch, or even just an idea. But before the end of the
  146. process the following should exist:
  147. - ChangeLog entry (see the GNU coding standards for details).
  148. - Changes to the NEWS file and cvs.texinfo, if the change is a
  149. user-visible change worth mentioning.
  150. - Somewhere, a description of what the patch fixes (often in
  151. comments in the code, or maybe the ChangeLog or documentation).
  152. - Most of the time, a test case (see TESTS). It can be quite
  153. frustrating to fix a bug only to see it reappear later, and adding
  154. the case to the testsuite, where feasible, solves this and other
  155. problems. See the TESTS file for notes on writing new tests.
  156. If you solve several unrelated problems, it is generally easier to
  157. consider the desirability of the changes if there is a separate patch
  158. for each issue. Use context diffs or unidiffs for patches.
  159. Include words like "I grant permission to distribute this patch under
  160. the terms of the GNU Public License" with your patch. By sending a
  161. patch to bug-cvs@nongnu.org, you implicitly grant this permission.
  162. Submitting a patch to bug-cvs is the way to reach the people who have
  163. signed up to receive such submissions (including CVS developers), but
  164. there may or may not be much (or any) response. If you want to pursue
  165. the matter further, you are probably best off working with the larger
  166. CVS community. Distribute your patch as widely as desired (mailing
  167. lists, newsgroups, web sites, whatever). Write a web page or other
  168. information describing what the patch is for. It is neither practical
  169. nor desirable for all/most contributions to be distributed through the
  170. "official" (whatever that means) mechanisms of CVS releases and CVS
  171. developers. Now, the "official" mechanisms do try to incorporate
  172. those patches which seem most suitable for widespread usage, together
  173. with test cases and documentation. So if a patch becomes sufficiently
  174. popular in the CVS community, it is likely that one of the CVS
  175. developers will eventually try to do something with it. But dealing
  176. with the CVS developers may be the last step of the process rather
  177. than the first.
  178. * What is the schedule for the next release?
  179. There isn't one. That is, upcoming releases are not announced (or
  180. even hinted at, really) until the feature freeze which is
  181. approximately 2 weeks before the final release (at this time test
  182. releases start appearing and are announced on info-cvs). This is
  183. intentional, to avoid a last minute rush to get new features in.
  184. * Mailing lists
  185. In addition to the mailing lists listed in the README file, developers should
  186. take particular note of the following mailling lists:
  187. bug-cvs: This is the list which users are requested to send bug reports
  188. to. General CVS development and design discussions also take place on
  189. this list.
  190. info-cvs: This list is intended for user questions, but general CVS
  191. development and design discussions sometimes take place on this list.
  192. cvs-cvs: The only messages sent to this list are sent
  193. automatically, via the CVS `loginfo' mechanism, when someone
  194. checks something in to the master CVS repository.
  195. cvs-test-results: The only messages sent to this list are sent
  196. automatically, daily, by a script which runs "make check"
  197. and "make remotecheck" on the master CVS sources.
  198. To subscribe to any of these lists, send mail to <list>-request@nongnu.org
  199. or visit http://savannah.nongnu.org/mail/?group=cvs and follow the instructions
  200. for the list you wish to subscribe to.