diff options
Diffstat (limited to 'doc/developer/workflow.rst')
| -rw-r--r-- | doc/developer/workflow.rst | 128 |
1 files changed, 104 insertions, 24 deletions
diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 291a277c6b..f025c47bb4 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -479,6 +479,16 @@ checkpatch.sh When convenient it is preferred that these be cleaned up inline, but this is not required. + In general, a developer should heed the information reported by checkpatch. + However, some flexibility is needed for cases where human judgement yields + better clarity than the script. Accordingly, it may be appropriate to + ignore some checkpatch.sh warnings per discussion among the submitter(s) + and reviewer(s) of a change. Misreporting of errors by the script is + possible. When this occurs, the exception should be handled either by + patching checkpatch to correct the false error report, or by documenting the + exception in this document under :ref:`style-exceptions`. If the incorrect + report is likely to appear again, a checkpatch update is preferred. + If the script finds one or more WARNINGs it will exit with 1. If it finds one or more ERRORs it will exit with 2. @@ -488,6 +498,12 @@ responsibility for properly formatting your code ultimately lies on the shoulders of the submitter. As such, it is recommended to double-check the results of these tools to avoid delays in merging your submission. +In some cases, these tools modify or flag the format in ways that go beyond or +even conflict [#tool_style_conflicts]_ with the canonical documented Linux +kernel style. In these cases, the Linux kernel style takes priority; +non-canonical issues flagged by the tools are not compulsory but rather are +opportunities for discussion among the submitter(s) and reviewer(s) of a change. + **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 @@ -533,6 +549,8 @@ necessary replacements. | u_long | unsigned long | +-----------+--------------------------+ +.. _style-exceptions: + Exceptions ^^^^^^^^^^ @@ -571,6 +589,23 @@ BSD coding style applies to: - ``ldpd/`` + +Specific Exceptions +^^^^^^^^^^^^^^^^^^^ + +Most of the time checkpatch errors should be corrected. Occasionally as a group +maintainers will decide to ignore certain stylistic issues. Usually this is +because correcting the issue is not possible without large unrelated code +changes. When an exception is made, if it is unlikely to show up again and +doesn't warrant an update to checkpatch, it is documented here. + ++------------------------------------------+---------------------------------------------------------------+ +| Issue | Ignore Reason | ++==========================================+===============================================================+ +| DEFPY_HIDDEN, DEFPY_ATTR: complex macros | DEF* macros cannot be wrapped in parentheses without updating | +| should be wrapped in parentheses | all usages of the macro, which would be highly disruptive. | ++------------------------------------------+---------------------------------------------------------------+ + Compile-time conditional code ----------------------------- @@ -633,7 +668,7 @@ AddressSanitizer instrumentation and run through a series of tests to look for any results. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-address-sanitizer to ``configure``. @@ -643,7 +678,7 @@ ThreadSanitizer detecting data races. If you are working on or around multithreaded code, extensive testing with this instrumtation enabled is *highly* recommended. You can enable it by passing:: - + --enable-thread-sanitizer to ``configure``. @@ -652,7 +687,7 @@ MemorySanitizer Similar to AddressSanitizer, this tool provides runtime instrumentation for detecting use of uninitialized heap memory. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-memory-sanitizer to ``configure``. @@ -740,27 +775,33 @@ FRR uses Sphinx+RST as its documentation system. The document you are currently reading was generated by Sphinx from RST source in :file:`doc/developer/workflow.rst`. The documentation is structured as follows: -+-----------------------+--------------------------------------------------------------+ -| Directory | Contents | -+=======================+==============================================================+ -| :file:`doc/user` | User documentation; configuration guides; protocol overviews | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/developer` | Developer's documentation; API specs; datastructures; | -| | architecture overviews; project management procedure | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/manpages` | Source for manpages | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/figures` | Images and diagrams | -+-----------------------+--------------------------------------------------------------+ - -Each of these directories, with the exception of :file:`doc/figures`, contains -a Sphinx-generated Makefile and configuration script :file:`conf.py` used to -set various document parameters. The makefile can be used for a variety of -targets; invoke `make help` in any of these directories for a listing of -available output formats. For convenience, there is a top-level -:file:`Makefile.am` that has targets for PDF and HTML documentation for both -developer and user documentation, respectively. That makefile is also -responsible for building manual pages packed with distribution builds. ++-----------------------+-------------------------------------------+ +| Directory | Contents | ++=======================+===========================================+ +| :file:`doc/user` | User documentation; configuration guides; | +| | protocol overviews | ++-----------------------+-------------------------------------------+ +| :file:`doc/developer` | Developer's documentation; API specs; | +| | datastructures; architecture overviews; | +| | project management procedure | ++-----------------------+-------------------------------------------+ +| :file:`doc/manpages` | Source for manpages | ++-----------------------+-------------------------------------------+ +| :file:`doc/figures` | Images and diagrams | ++-----------------------+-------------------------------------------+ +| :file:`doc/extra` | Miscellaneous Sphinx extensions, scripts, | +| | customizations, etc. | ++-----------------------+-------------------------------------------+ + +Each of these directories, with the exception of :file:`doc/figures` and +:file:`doc/extra`, contains a Sphinx-generated Makefile and configuration +script :file:`conf.py` used to set various document parameters. The makefile +can be used for a variety of targets; invoke `make help` in any of these +directories for a listing of available output formats. For convenience, there +is a top-level :file:`Makefile.am` that has targets for PDF and HTML +documentation for both developer and user documentation, respectively. That +makefile is also responsible for building manual pages packed with distribution +builds. Indent and styling should follow existing conventions: @@ -855,6 +896,15 @@ your implementation of a new BGP draft should go in the BGP chapter instead of being its own chapter. If you are adding a new protocol daemon, please create a new chapter. +FRR Specific Markup +------------------- + +FRR has some customizations applied to the Sphinx markup that go a long way +towards making documentation easier to use, write and maintain. + +CLI Commands +^^^^^^^^^^^^ + When documenting CLI please use a combination of the ``.. index::`` and ``.. clicmd::`` directives. For example, the command :clicmd:`show pony` would be documented as follows: @@ -888,5 +938,35 @@ When documented this way, CLI commands can be cross referenced with the This is very helpful for users who want to quickly remind themselves what a particular command does. +Configuration Snippets +^^^^^^^^^^^^^^^^^^^^^^ + +When putting blocks of example configuration please use the +``.. code-block::`` directive and specify ``frr`` as the highlighting language, +as in the following example. This will tell Sphinx to use a custom Pygments +lexer to highlight FRR configuration syntax. + +.. code-block:: rest + + .. code-block:: frr + + ! + ! Example configuration file. + ! + log file /tmp/log.log + service integrated-vtysh-config + ! + ip route 1.2.3.0/24 reject + ipv6 route de:ea:db:ee:ff::/64 reject + ! + + .. _GitHub: https://github.com/frrouting/frr .. _GitHub issues: https://github.com/frrouting/frr/issues + +.. rubric:: Footnotes + +.. [#tool_style_conflicts] For example, lines over 80 characters are allowed + for text strings to make it possible to search the code for them: please + see `Linux kernel style (breaking long lines and strings) <https://www.kernel.org/doc/html/v4.10/process/coding-style.html#breaking-long-lines-and-strings>`_ + and `Issue #1794 <https://github.com/FRRouting/frr/issues/1794>`_. |