[TOC]
+## General note on this document
+
+This document is "descriptive/post-factual" in that it documents pratices that
+are in use; it is not "definitive/pre-factual" in prescribing practices.
+
+This means that when a procedure changes, it is agreed upon, then put into
+practice, and then documented here. If this document doesn't match reality,
+it's the document that needs to be updated, not reality.
+
+
## Git Structure
The master Git for PROJECT resides on Github at
-There are 3 main branches for development and a release branch for each
+There is one main branch for development and a release branch for each
major release.
-New contributions are done against the head of the Develop branch. The CI
+New contributions are done against the head of the master branch. The CI
systems will pick up the Github Pull Requests or the new patch from
-Patchwork, run some basic build and functional tests and will merge them
-into the branch automatically on success.
-
-Code on the develop branch will then be further tested and reviewed by the
-community and merged to master on a regular interval.
+Patchwork, run some basic build and functional tests.
For each major release (1.0, 1.1 etc) a new release branch is created based
on the master.
+There was an attempt to use a "develop" branch automatically maintained by
+the CI system. This is not currently in active use, though the system is
+operational. If the "develop" branch is in active use and this paragraph
+is still here, this document obviously wasn't updated.
+
## Programming language, Tools and Libraries
### Code styling / format
-GNU coding standards apply. Indentation follows the result of invoking GNU
-indent (as of 2.2.8a) with the `-nut -nfc1` arguments.
+Coding style standards in FRR vary depending on location. Pre-existing
+code uses GNU coding standards. New code may use Linux kernel coding style.
+
+GNU coding style apply to the following parts:
+
+* lib/
+* zebra/
+* bgpd/
+* ospfd/
+* ospf6d/
+* isisd/
+* ripd/
+* ripngd/
+* vtysh/
+
+Linux kernel coding style applies to:
+
+* nhrpd/
+* watchfrr/
+* pimd/
+* lib/{checksum,hook,imsg-buffer,imsg,libfrr,md5,module,monotime,queue}.[ch]
+
+BSD coding style applies to:
+
+* ldpd/
+
+**Whitespace changes in untouched parts of the code are not acceptable in
+patches that change actual code.** To change/fix formatting issues, please
+create a separate patch that only does formatting changes and nothing else.
+
+It is acceptable to rewrap entire files to Linux kernel style, but this
+**MUST** come as a separate patch that does nothing other than this
+reformatting.
+
+
+#### GNU style
+
+For GNU coding style, Indentation follows the result of invoking GNU indent:
```
indent -nut -nfc1 file_for_submission.c
```
-Please don’t reformat existing files (or only sections modified by your
-changes), even if they don’t follow the standard. This makes it very hard to
-highlight the changes
+Originally, tabs were used instead of spaces, with tabs are every 8 columns.
+However, tab 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.
-### Changing / Deprecate an existing exported interface
-If changing an exported interface, please try to deprecate the interface in an
-orderly manner. If at all possible, try to retain the old deprecated interface
-as is, or functionally equivalent. Make a note of when the interface was
-deprecated and guard the deprecated interface definitions in the header file,
-i.e.:
+#### Linux kernel & BSD style
-```
-/* Deprecated: 20050406 */
-#if !defined(QUAGGA_NO_DEPRECATED_INTERFACES)
-#warning "Using deprecated <libname> (interface(s)|function(s))"
-...
-#endif /* QUAGGA_NO_DEPRECATED_INTERFACES */
-```
+These styles are documented externally:
+
+* [https://www.kernel.org/doc/Documentation/CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle).
+* [http://man.openbsd.org/style](http://man.openbsd.org/style)
-This is to ensure that the core Quagga sources do not use the deprecated
-interfaces (you should update Quagga sources to use new interfaces, if
-applicable), while allowing external sources to continue to build. Deprecated
-interfaces should be excised in the next unstable cycle.
+They are relatively similar but differ in details.
-Note: If you wish, you can test for GCC and use a function marked with the
-`deprecated` attribute. However, you must provide the warning for other
-compilers. If changing or removing a command definition, ensure that you
-properly deprecate it - use the `_DEPRECATED` form of the appropriate `DEFUN`
-macro. This is critical. Even if the command can no longer function, you MUST
-still implement it as a do-nothing stub.
+pimd deviates from Linux kernel style in using 2 spaces for indentation, with
+Tabs replacing 8 spaces, as well as adding a line break between `}` and `else`.
+It is acceptable to convert indentation in pimd/ to Linux kernel style, but
+please convert an entire file at a time. (Rationale: apart from 2-space
+indentation, the styles are sufficiently close to not upset when mixed.)
-Failure to follow this causes grief for systems administrators, as an upgrade
-may cause daemons to fail to start because of unrecognised commands. Deprecated
-commands should be excised in the next unstable cycle. A list of deprecated
-commands should be collated for each release.
+Unlike GNU style, these styles use tabs, not spaces.
### Compile-Time conditional code
Note that the former approach requires ensuring that `SOME_SYMBOL` will be
defined (watch your `AC_DEFINE`s).
+
+### Debug-Guards in code
+
+Debugs are an important methodology to allow developers to fix issues
+found in the code after it has been released. The caveat here is
+that the developer must remember that people will be using the code
+at scale and in ways that can be unexpected for the original implementor.
+As such debugs MUST be guarded in such a way that they can be turned off.
+This PROJECT has the ability to turn on/off debugs from the CLI and it is
+expected that the developer will use this convention to allow control
+of their debugs.
+
+### CLI-Changes
+
+CLI's are a complicated ugly beast. Additions or changes to the CLI
+should use a DEFUN to encapsulate one setting as much as is possible.
+Additionally as new DEFUN's are added to the system, documentation
+should be provided for the new commands.
projects / mirror_frr.git / blobdiff