pimd, ldpd and nhrpd all use slight variants of kernel style. (With "kernel" meaning either Linux, FreeBSD or OpenBSD - the styles are relatively close.)
Also drop RCS keyword foo. Signed-off-by: David Lamparter <equi...@opensourcerouting.org> --- With Timo hacking on nhrpd and Renato hacking on ldpd, this seems to be a good time to make HACKING.md reflect reality. FWIW, I would go further and accept Linux style on a per-file basis in other parts of Quagga. I can't find hard data on it, but it seems to be the most commonly used style in FOSS projects. Feedback appreciated, -David P.S.: how do people convert that document to something viewable? markdown_py produces somewhat-broken output for me. --- HACKING.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/HACKING.md b/HACKING.md index 3a449da..48617ce 100644 --- a/HACKING.md +++ b/HACKING.md @@ -8,42 +8,86 @@ date: \today include-before: \large This is a living document. Suggestions for updates, via the [quagga-dev list](http://lists.quagga.net/mailman/listinfo/quagga-dev), - are welcome. \newpage + are welcome. ... -\newpage +CODING STYLE +============ -GUIDELINES FOR HACKING ON QUAGGA {#sec:guidelines} -================================ +Coding style standards in Quagga vary depending on location. Pre-existing +code uses GNU coding standards. New daemons seem to use Linux kernel coding +style. For clarity, the exact list is: + +GNU coding style: + +- lib/ +- zebra/ +- bgpd/ +- ospfd/ +- ospf6d/ +- isisd/ +- ripd/ +- ripngd/ +- vtysh/ + +Linux kernel style: + +- pimd/ +- nhrpd/ +- ldpd/ -GNU coding standards apply. Indentation follows the result of -invoking GNU indent (as of 2.2.8a) with the -–nut argument. +In all cases, please absolutely avoid changing whitespace in locations where +your patches make no code change. (Rationale: random whitespace changes make +maintenance and merging work much more difficult.) + +GNU style details +----------------- + +For GNU coding style, Indentation follows the result of invoking GNU indent +(as of 2.2.8a) with the -–nut argument. Originally, tabs were used instead of spaces, with tabs are every 8 columns. However, tab’s interoperability issues mean space characters are now preferred for new changes. We generally only clean up whitespace when code is unmaintainable due to whitespace issues, to minimise merging conflicts. +Linux kernel style details +-------------------------- + +For Linux kernel coding style, please refer to +https://www.kernel.org/doc/Documentation/CodingStyle. The following deviations +apply to bits in Quagga: + +- pimd: + indentation is 2 spaces, with Tabs replacing 8 spaces. + Line break between `}` and `else`. +- nhrpd: + no systemic deviations +- ldpd: + there is an extra line break before the function name in definitions. + Function arguments in declarations have no names. + +For all of the above, patches may (but don't have to) move style towards +undeviated Linux kernel coding style. When converting indentation in pimd/, +please convert an entire file at a time and only do so when making significant +changes to it. (Rationale: apart from 2-space indentation, the styles are +sufficiently close to not upset when mixed.) + +Documentation +------------- + Be particularly careful not to break platforms/protocols that you cannot test. +RCS-style Id keywords are not used in Quagga, some leftovers being the +exception (particularly in pimd/). They should not be added on new files. +(Rationale: they are not terribly useful with git.) + New code should have good comments, which explain why the code is correct. Changes to existing code should in many cases upgrade the comments when necessary for a reviewer to conclude that the change has no unintended consequences. -Each file in the Git repository should have a git format-placeholder (like -an RCS Id keyword), somewhere very near the top, commented out appropriately -for the file type. The placeholder used for Quagga (replacing \<dollar\> -with \$) is: - -`$QuaggaId: <dollar>Format:%an, %ai, %h<dollar> $` - -See line 2 of HACKING.tex, the source for this document, for an example. - -This placeholder string will be expanded out by the ‘git archive’ commands, -which is used to generate the tar archives for snapshots and releases. - Please document fully the proper use of a new function in the header file in which it is declared. And please consult existing headers for documentation on how to use existing functions. In particular, please consult -- 2.3.6 _______________________________________________ Quagga-dev mailing list Quagga-dev@lists.quagga.net https://lists.quagga.net/mailman/listinfo/quagga-dev
