HACKING

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