HACKING 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317
  1. -*- mode: text; -*-
  2. $Id: HACKING,v 1.21 2005/11/10 10:21:19 paul Exp $
  3. GUIDELINES FOR HACKING ON QUAGGA
  4. [this is a draft in progress]
  5. GNU coding standards apply. Indentation follows the result of
  6. invoking GNU indent (as of 2.2.8a) with no arguments. Note that this
  7. uses tabs instead of spaces where possible for leading whitespace, and
  8. assumes that tabs are every 8 columns. Do not attempt to redefine the
  9. location of tab stops. Note also that some indentation does not
  10. follow GNU style. This is a historical accident, and we generally
  11. only clean up whitespace when code is unmaintainable due to whitespace
  12. issues, as fewer changes from zebra lead to easier merges.
  13. For GNU emacs, use indentation style "gnu".
  14. For Vim, use the following lines (note that tabs are at 8, and that
  15. softtabstop sets the indentation level):
  16. set tabstop=8
  17. set softtabstop=2
  18. set shiftwidth=2
  19. set noexpandtab
  20. Be particularly careful not to break platforms/protocols that you
  21. cannot test.
  22. New code should have good comments, and changes to existing code
  23. should in many cases upgrade the comments when necessary for a
  24. reviewer to conclude that the change has no unintended consequences.
  25. Each file in CVS should have the RCS keyword Id, somewhere very near
  26. the top, commented out appropriately for the file type. Just add
  27. <dollar>Id:<dollar>, replacing <dollar> with $. See line 2 of HACKING
  28. for an example; on checkout :$ is expanded to include the value.
  29. Please document fully the proper use of a new function in the header file
  30. in which it is declared. And please consult existing headers for
  31. documentation on how to use existing functions. In particular, please consult
  32. these header files:
  33. lib/log.h logging levels and usage guidance
  34. [more to be added]
  35. If changing an exported interface, please try to deprecate the interface in
  36. an orderly manner. If at all possible, try to retain the old deprecated
  37. interface as is, or functionally equivalent. Make a note of when the
  38. interface was deprecated and guard the deprecated interface definitions in
  39. the header file, ie:
  40. /* Deprecated: 20050406 */
  41. #if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
  42. #warning "Using deprecated <libname> (interface(s)|function(s))"
  43. ...
  44. #endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
  45. To ensure that the core Quagga sources do not use the deprecated interfaces
  46. (you should update Quagga sources to use new interfaces, if applicable)
  47. while allowing external sources to continue to build. Deprecated interfaces
  48. should be excised in the next unstable cycle.
  49. Note: If you wish, you can test for GCC and use a function
  50. marked with the 'deprecated' attribute. However, you must provide the
  51. #warning for other compilers.
  52. If changing or removing a command definition, *ensure* that you properly
  53. deprecate it - use the _DEPRECATED form of the appropriate DEFUN macro. This
  54. is *critical*. Even if the command can no longer function, you *must* still
  55. implement it as a do-nothing stub. Failure to follow this causes grief for
  56. systems administrators. Deprecated commands should be excised in the next
  57. unstable cycle. A list of deprecated commands should be collated for each
  58. release.
  59. See also below regarding SHARED LIBRARY VERSIONING.
  60. CHANGELOG
  61. Add a ChangeLog entry whenever changing code, except for minor fixes
  62. to a commit (with a ChangeLog entry) within the last few days.
  63. Most directories have a ChangeLog file; changes to code in that
  64. directory should go in the per-directory ChangeLog. Global or
  65. structural changes should also be mentioned in the top-level
  66. ChangeLog.
  67. Certain directories do not contain project code, but contain project
  68. meta-data, eg packaging information, changes to files in these
  69. directory may not require the global ChangeLog to be updated (at the
  70. discretion of the maintainer who usually maintains that meta-data).
  71. Also, CVS meta-data such as cvsignore files do not require ChangeLog
  72. updates, just a sane commit message.
  73. The ChangeLog should provide:
  74. * The date, in YYYY-MM-DD format
  75. * The author's name and email.
  76. * a short description of each change made
  77. * file by file
  78. * function by function (use of "ditto" is allowed)
  79. (detailed discussion of non-obvious reasoning behind and/or
  80. implications of a change should be made in comments in the code
  81. concerned). The changelog optionally may have a (general) description,
  82. to provide a short description of the general intent of the patch. The
  83. reason for such itemised ChangeLogs is to encourage the author to
  84. self-review every line of the patch, as well as provide reviewers an
  85. index of which changes are intended, along with a short description for
  86. each. E.g.:
  87. 2012-05-29 Joe Bar <joe@example.com>
  88. * (general) Add a new DOWN state to the frob state machine
  89. to allow the barinator to detect loss of frob.
  90. * frob.h: (struct frob) Add DOWN state flag.
  91. * frob.c: (frob_change) set/clear DOWN appropriately on state
  92. change.
  93. * bar.c: (barinate) Check frob for DOWN state.
  94. HACKING THE BUILD SYSTEM
  95. If you change or add to the build system (configure.ac, any Makefile.am,
  96. etc.), try to check that the following things still work:
  97. - make dist
  98. - resulting dist tarball builds
  99. - out-of-tree builds
  100. The quagga.net site relies on make dist to work to generate snapshots. It
  101. must work. Commong problems are to forget to have some additional file
  102. included in the dist, or to have a make rule refer to a source file without
  103. using the srcdir variable.
  104. RELEASE PROCEDURE
  105. Tag the repository with release tag (follow existing conventions).
  106. [This enables recreating the release, and is just good CM practice.]
  107. Check out the tag, and do a test build.
  108. In an empty directory, do a fresh checkout with -r <release-tag>
  109. [This makes the dates in the tarball be the modified dates in CVS.]
  110. ./configure
  111. make dist
  112. If any errors occur, move tags as needed and start over from the fresh
  113. checkouts. Do not append to tarballs, as this has produced
  114. non-standards-conforming tarballs in the past.
  115. [TODO: collation of a list of deprecated commands. Possibly can be scripted
  116. to extract from vtysh/vtysh_cmd.c]
  117. TOOL VERSIONS
  118. Require versions of support tools are listed in INSTALL.quagga.txt.
  119. Required versions should only be done with due deliberation, as it can
  120. cause environments to no longer be able to compile quagga.
  121. SHARED LIBRARY VERSIONING
  122. [this section is at the moment just gdt's opinion]
  123. Quagga builds several shared libaries (lib/libzebra, ospfd/libospf,
  124. ospfclient/libsopfapiclient). These may be used by external programs,
  125. e.g. a new routing protocol that works with the zebra daemon, or
  126. ospfapi clients. The libtool info pages (node Versioning) explain
  127. when major and minor version numbers should be changed. These values
  128. are set in Makefile.am near the definition of the library. If you
  129. make a change that requires changing the shared library version,
  130. please update Makefile.am.
  131. libospf exports far more than it should, and is needed by ospfapi
  132. clients. Only bump libospf for changes to functions for which it is
  133. reasonable for a user of ospfapi to call, and please err on the side
  134. of not bumping.
  135. There is no support intended for installing part of zebra. The core
  136. library libzebra and the included daemons should always be built and
  137. installed together.
  138. PATCH SUBMISSION
  139. * Send a clean diff against the head of CVS in unified diff format, eg by:
  140. cvs <cvs opts> diff -upwb ....
  141. * Include ChangeLog and NEWS entries as appropriate before the patch
  142. (or in it if you are 100% up to date). A good ChangeLog makes it easier to
  143. review a patch, hence failure to include a good ChangeLog is prejudicial
  144. to proper review of the patch, and hence the possibility of inclusion.
  145. * Include only one semantic change or group of changes per patch.
  146. * Do not make gratuitous changes to whitespace. See the w and b arguments
  147. to diff.
  148. * State on which platforms and with what daemons the patch has been
  149. tested. Understand that if the set of testing locations is small,
  150. and the patch might have unforeseen or hard to fix consequences that
  151. there may be a call for testers on quagga-dev, and that the patch
  152. may be blocked until test results appear.
  153. If there are no users for a platform on quagga-dev who are able and
  154. willing to verify -current occasionally, that platform may be
  155. dropped from the "should be checked" list.
  156. PATCH APPLICATION TO CVS
  157. * Only apply patches that meet the submission guidelines.
  158. * If a patch is large (perhaps more than 100 new/changed lines), tag
  159. the repository before and after the change with e.g. before-foo-fix
  160. and after-foo-fix.
  161. * If the patch might break something, issue a call for testing on the
  162. mailinglist.
  163. * Give an appropriate commit message, prefixed with a category name
  164. (either the name of the daemon, the library component or the general
  165. topic) and a one-line short summary of the change as the first line,
  166. suitable for use as a Subject in an email. The ChangeLog entry should
  167. suffice as the body of the commit message, if it does not, then the
  168. ChangeLog entry itself needs to be corrected. The commit message text
  169. should be identical to that added to the ChangeLog message. (One
  170. suggestion: when commiting, use your editor to read in the ChangeLog
  171. and delete all previous ChangeLogs.) An example:
  172. ----------------------------------------------------------------
  173. [frob] Defangulator needs to specify frob
  174. 2012-05-12 Joe Bar <joe@example.com>
  175. * frobinate.c: (frob_lookup) fix NULL dereference
  176. (defangulate) check whether frob is in state FROB_VALID
  177. before defangulating.
  178. ----------------------------------------------------------------
  179. * By committing a patch, you are responsible for fixing problems
  180. resulting from it (or backing it out).
  181. STABLE PLATFORMS AND DAEMONS
  182. The list of platforms that should be tested follow. This is a list
  183. derived from what quagga is thought to run on and for which
  184. maintainers can test or there are people on quagga-dev who are able
  185. and willing to verify that -current does or does not work correctly.
  186. BSD (Free, Net or Open, any platform) # without capabilities
  187. GNU/Linux (any distribution, i386)
  188. Solaris (strict alignment, any platform)
  189. [future: NetBSD/sparc64]
  190. The list of daemons that are thought to be stable and that should be
  191. tested are:
  192. zebra
  193. bgpd
  194. ripd
  195. ospfd
  196. ripngd
  197. Daemons which are in a testing phase are
  198. ospf6d
  199. isisd
  200. watchquagga
  201. IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS
  202. The source code of Quagga is based on two vendors:
  203. zebra_org (http://www.zebra.org/)
  204. isisd_sf (http://isisd.sf.net/)
  205. [20041105: Is isisd.sf.netf still where isisd word is happening, or is
  206. the quagga repo now the canonical place? The last tarball on sf is
  207. two years old. --gdt]
  208. In order to import source code, the following procedure should be used:
  209. * Tag the Current Quagga CVS repository:
  210. cvs tag import_isisd_sf_20031223
  211. * Import the source code into the Quagga's framework. You must not modified
  212. this source code. It will be merged later.
  213. cd dir_isisd
  214. export CVSROOT=:pserver:LOGIN@anoncvs.quagga.net:/var/cvsroot
  215. cvs import quagga/isisd isisd_sf isisd_sf_20031223
  216. ---COMMENTS---
  217. Vendor: [isisd_sf] Sampo's ISISd from Sourceforge
  218. Tag: [isisd_sf_20031217] Current CVS release
  219. ---
  220. * Update your Quagga's directory:
  221. cd dir_quagga
  222. cvs update -dP
  223. or
  224. cvs co -d quagga_isisd quagga
  225. * Merge the code, then commit:
  226. cvs commit