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 [Developer's Guidelines](#developers-guidelines))
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](https://www.kernel.org/doc/html/latest/process/submitting-patches.html) 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
236 `dir` should be the top level source directory under which the change was made.
237 For example, a change in bgpd/rfapi would be formatted as:
239 `bgpd: short summary`
241 The first line should be no longer than 50 characters. Subsequent lines should
242 be wrapped to 72 characters.
244 ### Source file header
246 New files need to have a Copyright header (see [License for
247 contributions](#license-for-contributions) above) added to the file. Preferred
248 form of the header is as follows:
252 * Title/Function of file
253 * Copyright (C) YEAR Author’s Name
255 * This program is free software; you can redistribute it and/or modify it
256 * under the terms of the GNU General Public License as published by the Free
257 * Software Foundation; either version 2 of the License, or (at your option)
260 * This program is distributed in the hope that it will be useful, but WITHOUT
261 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
262 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
265 * You should have received a copy of the GNU General Public License along
266 * with this program; see the file COPYING; if not, write to the Free Software
267 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
273 ### Adding copyright claims to existing files
275 When adding copyright claims for modifications to an existing file, please
276 preface the claim with "Portions: " on a line before it and indent the
277 "Copyright ..." string. If such a case already exists, add your indented claim
278 immediately after. E.g.:
282 Copyright (C) 2010 Entity A ....
283 Copyright (C) 2016 Your name [optional brief change description]
288 FRR uses Linux kernel style except where noted below. Code which does not
289 comply with these style guidelines will not be accepted.
291 To assist with compliance, in the project root there is a .clang-format
292 configuration file which can be used with the `clang-format` tool from the LLVM
293 project. In the `tools/` directory there is a Python script named `indent.py`
294 that wraps clang-format and handles some edge cases specific to FRR. If you are
295 submitting a new file, it is recommended to run that script over the new file
296 after ensuring that the latest stable release of `clang-format` is in your
299 **Whitespace changes in untouched parts of the code are not acceptable in
300 patches that change actual code.** To change/fix formatting issues, please
301 create a separate patch that only does formatting changes and nothing else.
303 #### Style documentation
304 Kernel and BSD styles are documented externally:
306 * [https://www.kernel.org/doc/html/latest/process/coding-style.html](https://www.kernel.org/doc/html/latest/process/coding-style.html)
307 * [http://man.openbsd.org/style](http://man.openbsd.org/style)
309 For GNU coding style, use `indent` with the following invocation:
312 indent -nut -nfc1 file_for_submission.c
317 FRR project code comes from a variety of sources, so there are some stylistic
318 exceptions in place. They are organized here by branch.
322 BSD coding style applies to:
326 `babeld` uses, approximately, the following style:
329 * Indents are 4 spaces
330 * Function return types are on their own line
333 **For `stable/3.0` and `stable/2.0`:**
335 GNU coding style apply to the following parts:
347 BSD coding style applies to:
354 FRRouting is a large and complex software project developed by many different
355 people over a long period of time. Without adequate documentation, it can be
356 exceedingly difficult to understand code segments, APIs and other interfaces.
357 In the interest of keeping the project healthy and maintainable, you should
358 make every effort to document your code so that other people can understand
359 what it does without needing to closely read the code itself.
361 Some specific guidelines that contributors should follow are:
363 * Functions exposed in header files should have descriptive comments above
364 their signatures in the header file. At a minimum, a function comment should
365 contain information about the return value, parameters, and a general summary
366 of the function's purpose. Documentation on parameter values can be omitted
367 if it is (very) obvious what they are used for.
369 Function comments must follow the style for multiline comments laid out in
370 the kernel style guide.
376 * Determines whether or not a string is cool.
378 * @param text - the string to check for coolness
379 * @param is_clccfc - whether capslock is cruise control for cool
380 * @return 7 if the text is cool, 0 otherwise
382 int check_coolness(const char *text, bool is_clccfc);
385 The Javadoc-style annotations are not required, but you should still strive to
386 make it equally clear what parameters and return values are used for.
388 * Static functions should have descriptive comments in the same form as above
389 if what they do is not immediately obvious. Use good engineering judgement
390 when deciding whether a comment is necessary. If you are unsure, document
393 * Global variables, static or not, should have a comment describing their use.
395 * **For new code in `lib/`, these guidelines are hard requirements.**
398 If you are contributing code that adds significant user-visible functionality
399 or introduces a new API, please document it in `doc/`. Markdown and LaTeX are
400 acceptable formats, although Markdown is currently preferred for new
401 documentation. This may change in the near future.
403 Finally, if you come across some code that is undocumented and feel like going
404 above and beyond, document it! We absolutely appreciate and accept patches that
405 document previously undocumented code.
407 ### Compile-time conditional code
409 Many users access FRR via binary packages from 3rd party sources; compile-time
410 code puts inclusion/exclusion in the hands of the package maintainer. Please
411 think very carefully before making code conditional at compile time, as it
412 increases regression testing, maintenance burdens, and user confusion. In
413 particular, please avoid gratuitous `--enable-…` switches to the configure
414 script - in general, code should be of high quality and in working condition,
415 or it shouldn’t be in FRR at all.
417 When code must be compile-time conditional, try have the compiler make it
418 conditional rather than the C pre-processor so that it will still be checked by
419 the compiler, even if disabled. For example,
431 #endif /* SOME_SYMBOL */
434 Note that the former approach requires ensuring that `SOME_SYMBOL` will be
435 defined (watch your `AC_DEFINE`s).
437 ### Debug-guards in code
439 Debugging statements are an important methodology to allow developers to fix
440 issues found in the code after it has been released. The caveat here is that
441 the developer must remember that people will be using the code at scale and in
442 ways that can be unexpected for the original implementor. As such debugs
443 **MUST** be guarded in such a way that they can be turned off. FRR has the
444 ability to turn on/off debugs from the CLI and it is expected that the
445 developer will use this convention to allow control of their debugs.
449 CLI's are a complicated ugly beast. Additions or changes to the CLI should use
450 a DEFUN to encapsulate one setting as much as is possible. Additionally as new
451 DEFUN's are added to the system, documentation should be provided for the new
454 ### Backwards Compatibility
456 As a general principle, changes to CLI and code in the lib/ directory should be
457 made in a backwards compatible fashion. This means that changes that are purely
458 stylistic in nature should be avoided, e.g., renaming an existing macro or
459 library function name without any functional change. When adding new parameters
460 to common functions, it is also good to consider if this too should be done in
461 a backward compatible fashion, e.g., by preserving the old form in addition to
464 This is not to say that minor or even major functional changes to CLI and
465 common code should be avoided, but rather that the benefit gained from a change
466 should be weighed against the added cost/complexity to existing code. Also,
467 that when making such changes, it is good to preserve compatibility when
468 possible to do so without introducing maintenance overhead/cost. It is also
469 important to keep in mind, existing code includes code that may reside in
470 private repositories (and is yet to be submitted) or code that has yet to be
471 migrated from Quagga to FRR.
473 That said, compatibility measures can (and should) be removed when either:
475 * they become a significant burden, e.g. when data structures change and the
476 compatibility measure would need a complex adaptation layer or becomes
478 * some measure of time (dependent on the specific case) has passed, so that the
479 compatibility grace period is considered expired.
481 In all cases, compatibility pieces should be marked with compiler/preprocessor
482 annotations to print warnings at compile time, pointing to the appropriate
483 update path. A `-Werror` build should fail if compatibility bits are used.
487 When in doubt, follow the guidelines in the Linux kernel style guide, or ask on
488 the development mailing list / public Slack instance.