2 %% $QuaggaId: Format:%an, %ai, %h$ $
4 \documentclass[oneside
]{article
}
6 \usepackage[bookmarks,colorlinks=true
]{hyperref
}
8 \title{Conventions for working on Quagga
}
13 This is a living
document. Suggestions for updates, via the
14 \href{http://lists.quagga.net/mailman/listinfo/quagga-dev
}{quagga-dev list
},
19 \section{GUIDELINES FOR HACKING ON QUAGGA
}
20 \label{sec:guidelines
}
23 GNU coding standards apply. Indentation follows the result of
24 invoking GNU indent (as of
2.2.8a) with the --nut argument.
26 Originally, tabs were used instead of spaces, with tabs are every
8 columns.
27 However, tab's interoperability issues mean space characters are now preferred for
28 new changes. We generally only clean up whitespace when code is unmaintainable
29 due to whitespace issues, to minimise merging conflicts.
31 Be particularly careful not to break platforms/protocols that you
34 New code should have good comments, which explain why the code is correct.
35 Changes to existing code should in many cases upgrade the comments when
36 necessary for a reviewer to conclude that the change has no unintended
39 Each file in the Git repository should have a git format-placeholder (like
40 an RCS Id keyword), somewhere very near the top, commented out appropriately
41 for the file type. The placeholder used for Quagga (replacing <dollar> with
44 \verb|$QuaggaId: <dollar>Format:
%an, %ai, %h<dollar> $|
46 See line
2 of HACKING.tex, the source for this
document, for an example.
48 This placeholder string will be expanded out by the `git archive' commands,
49 which is used to generate the tar archives for snapshots and releases.
51 Please
document fully the proper use of a new function in the header file
52 in which it is declared. And please consult existing headers for
53 documentation on how to use existing functions. In particular, please consult
57 \item{lib/log.h
} logging levels and usage guidance
58 \item{[more to be added
]}
61 If changing an exported interface, please try to deprecate the interface in
62 an orderly manner. If at all possible, try to retain the old deprecated
63 interface as is, or functionally equivalent. Make a note of when the
64 interface was deprecated and guard the deprecated interface definitions in
65 the header file, i.e.:
68 /* Deprecated:
20050406 */
69 #if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
70 #warning "Using deprecated <libname> (interface(s)|function(s))"
72 #endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
75 This is to ensure that the core Quagga sources do not use the deprecated
76 interfaces (you should update Quagga sources to use new interfaces, if
77 applicable), while allowing external sources to continue to build.
78 Deprecated interfaces should be excised in the next unstable cycle.
80 Note: If you wish, you can test for GCC and use a function
81 marked with the 'deprecated' attribute. However, you must provide the
82 warning for other compilers.
84 If changing or removing a command definition,
\emph{ensure
} that you
85 properly deprecate it - use the
\_DEPRECATED form of the appropriate DEFUN
86 macro. This is
\emph{critical
}. Even if the command can no longer
87 function, you
\emph{MUST
} still implement it as a do-nothing stub.
89 Failure to follow this causes grief for systems administrators, as an
90 upgrade may cause daemons to fail to start because of unrecognised commands.
91 Deprecated commands should be excised in the next unstable cycle. A list of
92 deprecated commands should be collated for each release.
94 See also section~
\ref{sec:dll-versioning
} below regarding SHARED LIBRARY
97 \section{YOUR FIRST CONTRIBUTIONS
}
99 Routing protocols can be very complex sometimes. Then, working with an
100 Opensource community can be complex too, but usually friendly with
101 anyone who is ready to be willing to do it properly.
105 \item First, start doing simple tasks. Quagga's patchwork is a good place
106 to start with. Pickup some patches, apply them on your git trie,
107 review them and send your ack't or review comments. Then, a
108 maintainer will apply the patch if ack't or the author will
109 have to provide a new update. It help a lot to drain the
111 See
\url{http://patchwork.quagga.net/project/quagga/list/
}
113 \item The more you'll review patches from patchwork, the more the
114 Quagga's maintainers will be willing to consider some patches you will
117 \item start using git clone, pwclient
\url{http://patchwork.quagga.net/help/pwclient/
}
120 $ pwclient list -s new
123 179 New
[quagga-dev,
6648] Re: quagga on FreeBSD
4.11 (gcc-
2.95)
124 181 New
[quagga-dev,
6660] proxy-arp patch
127 $ pwclient git-am
1046
132 \section{HANDY GUIDELINES FOR MAINTAINERS
}
134 Get your cloned trie:
136 git clone vjardin@git.sv.gnu.org:/srv/git/quagga.git
139 Apply some ack't patches:
142 Applying patch
#1046 using 'git am'
143 Description:
[quagga-dev,
11595] zebra: route_unlock_node is missing in "show ip
[v6
] route <prefix>" commands
144 Applying: zebra: route_unlock_node is missing in "show ip
[v6
] route <prefix>" commands
147 Run a quick review. If the ack't was not done properly, you know who you have
155 Set the patch to accepted on patchwork
157 pwclient update -s Accepted
1046
160 \section{COMPILE-TIME CONDITIONAL CODE
}
162 Please think very carefully before making code conditional at compile time,
163 as it increases maintenance burdens and user confusion. In particular,
164 please avoid gratuitous --enable-
\ldots switches to the configure script -
165 typically code should be good enough to be in Quagga, or it shouldn't be
168 When code must be compile-time conditional, try have the compiler make it
169 conditional rather than the C pre-processor - so that it will still be
170 checked by the compiler, even if disabled. I.e. this:
182 #endif /* SOME_SYMBOL */
185 Note that the former approach requires ensuring that SOME
\_SYMBOL will be
186 defined (watch your AC
\_DEFINEs).
189 \section{COMMIT MESSAGES
}
191 The commit message requirements are:
195 \item The message
\emph{MUST
} provide a suitable one-line summary followed
196 by a blank line as the very first line of the message, in the form:
198 \verb|topic: high-level, one line summary|
200 Where topic would tend to be name of a subdirectory, and/or daemon, unless
201 there's a more suitable topic (e.g. 'build'). This topic is used to
202 organise change summaries in release announcements.
204 \item It should have a suitable "body", which tries to address the
205 following areas, so as to help reviewers and future browsers of the
206 code-base understand why the change is correct (note also the code
207 comment requirements):
211 \item The motivation for the change (does it fix a bug, if so which?
214 \item The general approach taken, and trade-offs versus any other
217 \item Any testing undertaken or other information affecting the confidence
218 that can be had in the change.
220 \item Information to allow reviewers to be able to tell which specific
221 changes to the code are intended (and hence be able to spot any accidental
227 The one-line summary must be limited to
54 characters, and all other
228 lines to
72 characters.
230 Commit message bodies in the Quagga project have typically taken the
234 \item An optional introduction, describing the change generally.
235 \item A short description of each specific change made, preferably:
236 \begin{itemize
} \item file by file
237 \begin{itemize
} \item function by function (use of "ditto", or globs is
243 Contributors are strongly encouraged to follow this form.
245 This itemised commit messages allows reviewers to have confidence that the
246 author has self-reviewed every line of the patch, as well as providing
247 reviewers a clear index of which changes are intended, and descriptions for
248 them (C-to-english descriptions are not desirable - some discretion is
249 useful). For short patches, a per-function/file break-down may be
250 redundant. For longer patches, such a break-down may be essential. A
251 contrived example (where the general discussion is obviously somewhat
252 redundant, given the one-line summary):
254 \begin{quote
}\begin{verbatim
}
255 zebra: Enhance frob FSM to detect loss of frob
257 Add a new DOWN state to the frob state machine to allow the barinator to
260 * frob.h: (struct frob) Add DOWN state flag.
261 * frob.c: (frob_change) set/clear DOWN appropriately on state change.
262 * bar.c: (barinate) Check frob for DOWN state.
263 \end{verbatim
}\end{quote
}
265 Please have a look at the git commit logs to get a feel for what the norms
268 Note that the commit message format follows git norms, so that ``git
269 log --oneline'' will have useful output.
271 \section{HACKING THE BUILD SYSTEM
}
273 If you change or add to the build system (configure.ac, any Makefile.am,
274 etc.), try to check that the following things still work:
278 \item resulting dist tarball builds
279 \item out-of-tree builds
282 The quagga.net site relies on make dist to work to generate snapshots. It
283 must work. Common problems are to forget to have some additional file
284 included in the dist, or to have a make rule refer to a source file without
285 using the srcdir variable.
288 \section{RELEASE PROCEDURE
}
291 \item Tag the appropriate commit with a release tag (follow existing
294 [This enables recreating the release, and is just good CM practice.
]
296 \item Create a fresh tar archive of the quagga.net repository, and do a test
301 git commit -m "release:
0.99.99.99"
302 git tag -u
54CD2E60 quagga-
0.99.99.99
303 git push savannah tag quagga-
0.99.99.99
305 git archive --prefix=quagga-release/ quagga-
0.99.99.99 | tar xC /tmp
306 git log quagga-
0.99.99.98..quagga-
0.99.99.99 > \
307 /tmp/quagga-release/quagga-
0.99.99.99.changelog.txt
308 cd /tmp/quagga-release
315 gunzip < quagga-
0.99.99.99.tar.gz > quagga-
0.99.99.99.tar
316 xz -
6e < quagga-
0.99.99.99.tar > quagga-
0.99.99.99.tar.xz
317 gpg -u
54CD2E60 -a --detach-sign quagga-
0.99.99.99.tar
319 scp quagga-
0.99.99.99.* username@dl.sv.nongnu.org:/releases/quagga
322 Do NOT do this in a subdirectory of the Quagga sources, autoconf will think
323 it's a sub-package and fail to include neccessary files.
325 \item Add the version number on https://bugzilla.quagga.net/, under
326 Administration, Products, "Quagga", Edit versions, Add a version.
327 \item Edit the wiki on https://wiki.quagga.net/wiki/index.php/Release
\_status
328 \item Post a news entry on Savannah
329 \item Send a mail to quagga-dev and quagga-users
332 The tarball which `make dist' creates is the tarball to be released! The
333 git-archive step ensures you're working with code corresponding to that in
334 the official repository, and also carries out keyword expansion. If any
335 errors occur, move tags as needed and start over from the fresh checkouts.
336 Do not append to tarballs, as this has produced non-standards-conforming
337 tarballs in the past.
339 See also:
\url{http://wiki.quagga.net/index.php/Main/Processes
}
341 [TODO: collation of a list of deprecated commands. Possibly can be scripted
342 to extract from vtysh/vtysh
\_cmd.c
]
345 \section{TOOL VERSIONS
}
347 Require versions of support tools are listed in INSTALL.quagga.txt.
348 Required versions should only be done with due deliberation, as it can
349 cause environments to no longer be able to compile quagga.
352 \section{SHARED LIBRARY VERSIONING
}
353 \label{sec:dll-versioning
}
355 [this section is at the moment just gdt's opinion
]
357 Quagga builds several shared libaries (lib/libzebra, ospfd/libospf,
358 ospfclient/libsopfapiclient). These may be used by external programs,
359 e.g. a new routing protocol that works with the zebra daemon, or
360 ospfapi clients. The libtool info pages (node Versioning) explain
361 when major and minor version numbers should be changed. These values
362 are set in Makefile.am near the definition of the library. If you
363 make a change that requires changing the shared library version,
364 please update Makefile.am.
366 libospf exports far more than it should, and is needed by ospfapi
367 clients. Only bump libospf for changes to functions for which it is
368 reasonable for a user of ospfapi to call, and please err on the side
371 There is no support intended for installing part of zebra. The core
372 library libzebra and the included daemons should always be built and
376 \section{GIT COMMIT SUBMISSION
}
377 \label{sec:git-submission
}
379 The preferred method for submitting changes is to provide git commits via a
380 publicly-accessible git repository, which the maintainers can easily pull.
382 The commits should be in a branch based off the Quagga.net master - a
383 "feature branch". Ideally there should be no commits to this branch other
384 than those in master, and those intended to be submitted. However, merge
385 commits to this branch from the Quagga master are permitted, though strongly
386 discouraged - use another (potentially local and throw-away) branch to test
387 merge with the latest Quagga master.
389 Recommended practice is to keep different logical sets of changes on
390 separate branches - "topic" or "feature" branches. This allows you to still
391 merge them together to one branch (potentially local and/or "throw-away")
392 for testing or use, while retaining smaller, independent branches that are
395 All content guidelines in section
\ref{sec:patch-submission
}, PATCH
399 \section{PATCH SUBMISSION
}
400 \label{sec:patch-submission
}
404 \item For complex changes, contributors are strongly encouraged to first
405 start a design discussion on the quagga-dev list
\emph{before
}
408 \item Send a clean diff against the 'master' branch of the quagga.git
409 repository, in unified diff format, preferably with the '-p' argument to
410 show C function affected by any chunk, and with the -w and -b arguments to
411 minimise changes. E.g:
413 git diff -up mybranch..remotes/quagga.net/master
415 It is preferable to use git format-patch, and even more preferred to
416 publish a git repository (see GIT COMMIT SUBMISSION, section
417 \ref{sec:git-submission
}).
419 If not using git format-patch, Include the commit message in the email.
421 \item After a commit, code should have comments explaining to the reviewer
422 why it is correct, without reference to history. The commit message
423 should explain why the change is correct.
425 \item Include NEWS entries as appropriate.
427 \item Include only one semantic change or group of changes per patch.
429 \item Do not make gratuitous changes to whitespace. See the w and b arguments
432 \item Changes should be arranged so that the least controversial and most
433 trivial are first, and the most complex or more controversial are
434 last. This will maximise how many the Quagga maintainers can merge,
435 even if some other commits need further work.
437 \item Providing a unit-test is strongly encouraged. Doing so will make it
438 much easier for maintainers to have confidence that they will be able
439 to support your change.
441 \item New code should be arranged so that it easy to verify and test. E.g.
442 stateful logic should be separated out from functional logic as much as
443 possible: wherever possible, move complex logic out to smaller helper
444 functions which access no state other than their arguments.
446 \item State on which platforms and with what daemons the patch has been
447 tested. Understand that if the set of testing locations is small,
448 and the patch might have unforeseen or hard to fix consequences that
449 there may be a call for testers on quagga-dev, and that the patch
450 may be blocked until test results appear.
452 If there are no users for a platform on quagga-dev who are able and
453 willing to verify -current occasionally, that platform may be
454 dropped from the "should be checked" list.
458 \section{PATCH APPLICATION
}
462 \item Only apply patches that meet the submission guidelines.
464 \item If the patch might break something, issue a call for testing on the
467 \item Give an appropriate commit message (see above), and use the --author
468 argument to git-commit, if required, to ensure proper attribution (you
469 should still be listed as committer)
471 \item Immediately after commiting, double-check (with git-log and/or gitk).
472 If there's a small mistake you can easily fix it with `git commit
475 \item When merging a branch, always use an explicit merge commit. Giving
476 --no-ff ensures a merge commit is created which documents ``this human
477 decided to merge this branch at this time''.
480 \section{STABLE PLATFORMS AND DAEMONS
}
482 The list of platforms that should be tested follow. This is a list
483 derived from what quagga is thought to run on and for which
484 maintainers can test or there are people on quagga-dev who are able
485 and willing to verify that -current does or does not work correctly.
488 \item BSD (Free, Net or Open, any platform)
489 \item GNU/Linux (any distribution, i386)
490 \item Solaris (strict alignment, any platform)
491 \item future: NetBSD/sparc64
494 The list of daemons that are thought to be stable and that should be
504 Daemons which are in a testing phase are
512 \section{IMPORT OR UPDATE VENDOR SPECIFIC ROUTING PROTOCOLS
}
514 The source code of Quagga is based on two vendors:
516 \verb|zebra_org| (
\url{http://www.zebra.org/
})
517 \verb|isisd_sf| (
\url{http://isisd.sf.net/
})
519 To import code from further sources, e.g. for archival purposes without
520 necessarily having to review and/or fix some changeset, create a branch from
524 git checkout -b archive/foo master
526 git commit -a "Joe Bar <joe@example.com>"
527 git push quagga archive/foo
530 presuming `quagga' corresponds to a file in your .git/remotes with
531 configuration for the appropriate Quagga.net repository.