1 Developing for FRRouting
2 =========================
8 ## General note on this document
10 This document is "descriptive/post-factual" in that it documents pratices that
11 are in use; it is not "definitive/pre-factual" in prescribing practices.
13 This means that when a procedure changes, it is agreed upon, then put into
14 practice, and then documented here. If this document doesn't match reality,
15 it's the document that needs to be updated, not reality.
20 The master Git for FRRouting resides on Github at
21 [https://github.com/frrouting/frr](https://github.com/FRRouting/frr)
23 ![git branches continually merging to the left from 3 lanes; float-right](doc/git_branches.svg
24 "git branch mechanics")
26 There is one main branch for development and a release branch for each major
29 New contributions are done against the head of the master branch. The CI
30 systems will pick up the Github Pull Requests or the new patch from Patchwork,
31 run some basic build and functional tests.
33 For each major release (1.0, 1.1 etc) a new release branch is created based on
36 There was an attempt to use a "develop" branch automatically maintained by the
37 CI system. This is not currently in active use, though the system is
38 operational. If the "develop" branch is in active use and this paragraph is
39 still here, this document obviously wasn't updated.
42 ## Programming language, Tools and Libraries
44 The core of FRRouting is written in C (gcc or clang supported) and makes use of
45 GNU compiler extensions. A few non-essential scripts are implemented in Perl
46 and Python. FRRouting requires the following tools to build distribution
47 packages: automake, autoconf, texinfo, libtool and gawk and various libraries
48 (i.e. libpam and libjson-c).
50 If your contribution requires a new library or other tool, then please
51 highlight this in your description of the change. Also make sure it’s supported
52 by all FRRouting platform OSes or provide a way to build without the library
53 (potentially without the new feature) on the other platforms.
55 Documentation should be written in Tex (.texi) or Markdown (.md) format with a
56 preference for Markdown.
61 Italicized lists are private.
64 |--------------------------------|------------------------------|
65 | Development | dev@lists.frrouting.org |
66 | Users & Operators | frog@lists.frrouting.org |
67 | Announcements | announce@lists.frrouting.org |
68 | _Security_ | security@lists.frrouting.org |
69 | _Technical Steering Committee_ | tsc@lists.frrouting.org |
74 The changelog will be the base for the release notes. A changelog entry for
75 your changes is usually not required and will be added based on your commit
76 messages by the maintainers. However, you are free to include an update to
77 the changelog with some better description. The changelog will be the base
78 for the release notes.
81 ## Submitting Patches and Enhancements
83 ### Pre-submission Checklist
85 * Format code (see [Coding style requirements](#coding-style-requirements))
86 * Verify and acknowledge license (see [License for contributions](#license-for-contributions))
87 * Ensure you have properly signed off (see [Signing Off](#signing-off))
88 * Test building with various configurations:
90 * Verify building source distribution:
91 * `make dist` (and try rebuilding from the resulting tar file)
94 * Document Regression Runs and plans for continued maintenance of the feature
96 ### License for contributions
98 FRRouting is under a “GPLv2 or later” license. Any code submitted must be
99 released under the same license (preferred) or any license which allows
100 redistribution under this GPLv2 license (eg MIT License).
104 Code submitted to FRRouting must be signed off. We have the same requirements
105 for using the signed-off-by process as the Linux kernel. In short, you must
106 include a signed-off-by tag in every patch.
108 `Signed-off-by:` this is a developer's certification that he or she has the
109 right to submit the patch for inclusion into the project. It is an agreement to
110 the Developer's Certificate of Origin (below). Code without a proper signoff
111 can not and will not be merged.
113 If you are unfamiliar with this process, you should read the [official policy
114 at kernel.org](http://www.kernel.org/doc/Documentation/SubmittingPatches) and
115 you might find this article about [participating in the Linux community on the
117 website](http://www.linuxfoundation.org/content/how-participate-linux-community-0)
118 to be a helpful resource.
120 In short, when you sign off on a commit, you assert your agreement to all of
123 > Developer's Certificate of Origin 1.1
125 > By making a contribution to this project, I certify that:
127 > (a) The contribution was created in whole or in part by me and I
128 > have the right to submit it under the open source license
129 > indicated in the file; or
131 > (b) The contribution is based upon previous work that, to the best
132 > of my knowledge, is covered under an appropriate open source
133 > license and I have the right under that license to submit that
134 > work with modifications, whether created in whole or in part
135 > by me, under the same open source license (unless I am
136 > permitted to submit under a different license), as indicated
139 > (c) The contribution was provided directly to me by some other
140 > person who certified (a), (b) or (c) and I have not modified
143 > (d) I understand and agree that this project and the contribution
144 > are public and that a record of the contribution (including all
145 > personal information I submit with it, including my sign-off) is
146 > maintained indefinitely and may be redistributed consistent with
147 > this project or the open source license(s) involved.
149 ### What do I submit my changes against?
151 We've documented where we would like to have the different fixes applied at
152 https://github.com/FRRouting/frr/wiki/Where-Do-I-create-a-Pull-Request-against%3F
153 If you are unsure where your submission goes, look at that document or ask a
156 ### Github pull requests
158 The preferred method of submitting changes is a Github pull request. Code
159 submitted by pull request will be automatically tested by one or more CI
160 systems. Once the automated tests succeed, other developers will review your
161 code for quality and correctness. After any concerns are resolved, your code
162 will be merged into the branch it was submitted against.
164 ### Patch submission via mailing list
166 As an alternative submission method, a patch can be mailed to the development
167 mailing list. Patches received on the mailing list will be picked up by
168 Patchwork and tested against the latest development branch.
170 The recommended way to send the patch (or series of NN patches) to the list is
171 by using `git send-email` as follows (assuming they are the N most recent
172 commit(s) in your git history:
175 git send-email -NN --annotate --to=dev@lists.frrouting.org
178 If your commits do not already contain a `Signed-off-by` line, then use the
179 following command to add it (after making sure you agree to the Developer
180 Certificate of Origin as outlined above):
183 git send-email -NN --annotate --signoff --to=dev@lists.frrouting.org
186 Submitting multi-commit patches as a Github pull request is **strongly
187 encouraged** and increases the probability of your patch getting reviewed and
188 merged in a timely manner.
191 ## After submitting your changes
193 * Watch for Continuous Integration (CI) Test results
194 * You should automatically receive an email with the test results within
195 less than 2 hrs of the submission. If you don’t get the email, then check
196 status on the github pull request (if submitted by pull request) or on
198 [https://patchwork.frrouting.org](https://patchwork.frrouting.org) (if
199 submitted as patch to mailing list).
200 * Please notify the development mailing list if you think something doesn’t
202 * If the tests failed:
203 * In general, expect the community to ignore the submission until the tests
205 * It is up to you to fix and resubmit.
206 * This includes fixing existing unit (“make test”) tests if your
207 changes broke or changed them.
208 * It also includes fixing distribution packages for the failing
209 platforms (ie if new libraries are required).
210 * Feel free to ask for help on the development list.
211 * Go back to the submission process and repeat until the tests pass.
213 * Wait for reviewers. Someone will review your code or be assigned to
215 * Respond to any comments or concerns the reviewer has.
216 * After all comments and concerns are addressed, expect your patch to be
218 * Watch out for questions on the mailing list. At this time there will be a
219 manual code review and further (longer) tests by various community members.
220 * Your submission is done once it is merged to the master branch.
223 ## Developer's Guidelines
227 Commit messages should be formatted in the same way as Linux kernel commit
228 messages. The format is roughly
230 ``` dir: short summary
234 `dir` should be the top level source directory under which the change was made.
235 For example, a change in bgpd/rfapi would be formatted as:
237 `bgpd: short summary`
239 The first line should be no longer than 50 characters. Subsequent lines should
240 be wrapped to 72 characters.
242 ### Source file header
244 New files need to have a Copyright header (see [License for
245 contributions](#license-for-contributions) above) added to the file. Preferred
246 form of the header is as follows:
250 * Title/Function of file
251 * Copyright (C) YEAR Author’s Name
253 * This program is free software; you can redistribute it and/or modify it
254 * under the terms of the GNU General Public License as published by the Free
255 * Software Foundation; either version 2 of the License, or (at your option)
258 * This program is distributed in the hope that it will be useful, but WITHOUT
259 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
260 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
263 * You should have received a copy of the GNU General Public License along
264 * with this program; see the file COPYING; if not, write to the Free Software
265 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
271 ### Adding copyright claims to existing files
273 When adding copyright claims for modifications to an existing file, please
274 preface the claim with "Portions: " on a line before it and indent the
275 "Copyright ..." string. If such a case already exists, add your indented claim
276 immediately after. E.g.:
280 Copyright (C) 2010 Entity A ....
281 Copyright (C) 2016 Your name [optional brief change description]
286 FRR uses Linux kernel style except where noted below. Code which does not
287 comply with these style guidelines will not be accepted.
289 To assist with compliance, in the project root there is a .clang-format
290 configuration file which can be used with the `clang-format` tool from the LLVM
291 project. In the `tools/` directory there is a Python script named `indent.py`
292 that wraps clang-format and handles some edge cases specific to FRR. If you are
293 submitting a new file, it is recommended to run that script over the new file
294 after ensuring that the latest stable release of `clang-format` is in your
297 **Whitespace changes in untouched parts of the code are not acceptable in
298 patches that change actual code.** To change/fix formatting issues, please
299 create a separate patch that only does formatting changes and nothing else.
301 #### Style documentation
302 Kernel and BSD styles are documented externally:
304 * [https://www.kernel.org/doc/html/latest/process/coding-style.html](https://www.kernel.org/doc/html/latest/process/coding-style.html)
305 * [http://man.openbsd.org/style](http://man.openbsd.org/style)
307 For GNU coding style, use `indent` with the following invocation:
310 indent -nut -nfc1 file_for_submission.c
315 FRR project code comes from a variety of sources, so there are some stylistic
316 exceptions in place. They are organized here by branch.
320 BSD coding style applies to:
324 `babeld` uses, approximately, the following style:
327 * Indents are 4 spaces
328 * Function return types are on their own line
331 **For `stable/3.0` and `stable/2.0`:**
333 GNU coding style apply to the following parts:
345 BSD coding style applies to:
352 FRRouting is a large and complex software project developed by many different
353 people over a long period of time. Without adequate documentation, it can be
354 exceedingly difficult to understand code segments, APIs and other interfaces.
355 In the interest of keeping the project healthy and maintainable, you should
356 make every effort to document your code so that other people can understand
357 what it does without needing to closely read the code itself.
359 Some specific guidelines that contributors should follow are:
361 * Functions exposed in header files should have descriptive comments above
362 their signatures in the header file. At a minimum, a function comment should
363 contain information about the return value, parameters, and a general summary
364 of the function's purpose. Documentation on parameter values can be omitted
365 if it is (very) obvious what they are used for.
367 Function comments must follow the style for multiline comments laid out in
368 the kernel style guide.
374 * Determines whether or not a string is cool.
376 * @param text - the string to check for coolness
377 * @param is_clccfc - whether capslock is cruise control for cool
378 * @return 7 if the text is cool, 0 otherwise
380 int check_coolness(const char *text, bool is_clccfc);
383 The Javadoc-style annotations are not required, but you should still strive to
384 make it equally clear what parameters and return values are used for.
386 * Static functions should have descriptive comments in the same form as above
387 if what they do is not immediately obvious. Use good engineering judgement
388 when deciding whether a comment is necessary. If you are unsure, document
391 * Global variables, static or not, should have a comment describing their use.
393 * **For new code in `lib/`, these guidelines are hard requirements.**
396 If you are contributing code that adds significant user-visible functionality
397 or introduces a new API, please document it in `doc/`. Markdown and LaTeX are
398 acceptable formats, although Markdown is currently preferred for new
399 documentation. This may change in the near future.
401 Finally, if you come across some code that is undocumented and feel like going
402 above and beyond, document it! We absolutely appreciate and accept patches that
403 document previously undocumented code.
405 ### Compile-time conditional code
407 Many users access FRR via binary packages from 3rd party sources; compile-time
408 code puts inclusion/exclusion in the hands of the package maintainer. Please
409 think very carefully before making code conditional at compile time, as it
410 increases regression testing, maintenance burdens, and user confusion. In
411 particular, please avoid gratuitous `--enable-…` switches to the configure
412 script - in general, code should be of high quality and in working condition,
413 or it shouldn’t be in FRR at all.
415 When code must be compile-time conditional, try have the compiler make it
416 conditional rather than the C pre-processor so that it will still be checked by
417 the compiler, even if disabled. For example,
429 #endif /* SOME_SYMBOL */
432 Note that the former approach requires ensuring that `SOME_SYMBOL` will be
433 defined (watch your `AC_DEFINE`s).
435 ### Debug-guards in code
437 Debugging statements are an important methodology to allow developers to fix
438 issues found in the code after it has been released. The caveat here is that
439 the developer must remember that people will be using the code at scale and in
440 ways that can be unexpected for the original implementor. As such debugs
441 **MUST** be guarded in such a way that they can be turned off. FRR has the
442 ability to turn on/off debugs from the CLI and it is expected that the
443 developer will use this convention to allow control of their debugs.
447 CLI's are a complicated ugly beast. Additions or changes to the CLI should use
448 a DEFUN to encapsulate one setting as much as is possible. Additionally as new
449 DEFUN's are added to the system, documentation should be provided for the new
452 ### Backwards Compatibility
454 As a general principle, changes to CLI and code in the lib/ directory should be
455 made in a backwards compatible fashion. This means that changes that are purely
456 stylistic in nature should be avoided, e.g., renaming an existing macro or
457 library function name without any functional change. When adding new parameters
458 to common functions, it is also good to consider if this too should be done in
459 a backward compatible fashion, e.g., by preserving the old form in addition to
462 This is not to say that minor or even major functional changes to CLI and
463 common code should be avoided, but rather that the benefit gained from a change
464 should be weighed against the added cost/complexity to existing code. Also,
465 that when making such changes, it is good to preserve compatibility when
466 possible to do so without introducing maintenance overhead/cost. It is also
467 important to keep in mind, existing code includes code that may reside in
468 private repositories (and is yet to be submitted) or code that has yet to be
469 migrated from Quagga to FRR.
471 That said, compatibility measures can (and should) be removed when either:
473 * they become a significant burden, e.g. when data structures change and the
474 compatibility measure would need a complex adaptation layer or becomes
476 * some measure of time (dependent on the specific case) has passed, so that the
477 compatibility grace period is considered expired.
479 In all cases, compatibility pieces should be marked with compiler/preprocessor
480 annotations to print warnings at compile time, pointing to the appropriate
481 update path. A `-Werror` build should fail if compatibility bits are used.
485 When in doubt, follow the guidelines in the Linux kernel style guide, or ask on
486 the development mailing list / public Slack instance.