From 02fe6f865ebed8d7a20e32689c084bbe0001543a Mon Sep 17 00:00:00 2001 From: David Lamparter Date: Mon, 23 Jan 2017 20:52:13 +0100 Subject: [PATCH] COMMUNITY.md: update CodingStyle & branching Also add a note that this is documentation, not law. Signed-off-by: David Lamparter --- COMMUNITY.md | 93 +++++- doc/git_branches.svg | 721 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 799 insertions(+), 15 deletions(-) diff --git a/COMMUNITY.md b/COMMUNITY.md index 52777da968..704c47a95e 100644 --- a/COMMUNITY.md +++ b/COMMUNITY.md @@ -2,6 +2,16 @@ [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 @@ -10,20 +20,21 @@ The master Git for PROJECT resides on Github at ![git branches continually merging to the left from 3 lanes; float-right](doc/git_branches.svg "git branch mechanics") -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 @@ -250,16 +261,72 @@ Portions: ### 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. + + +#### Linux kernel & BSD style + +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) + +They are relatively similar but differ in details. + +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.) + +Unlike GNU style, these styles use tabs, not spaces. + ### Compile-Time conditional code @@ -307,4 +374,4 @@ of their debugs. 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. \ No newline at end of file +should be provided for the new commands. diff --git a/doc/git_branches.svg b/doc/git_branches.svg index 3943eeacc8..0c2c96e39e 100644 --- a/doc/git_branches.svg +++ b/doc/git_branches.svg @@ -1,3 +1,720 @@ - -1.0ReleaseBranchMaster(Stable)Develop1.1ReleaseBranchVersion 1.0.a1Version 1.1.a1Version 1.1.a2Version 1.1.b1Patch Email (Patchwork)Github Pull RequestGithub Pull RequestPatch Email (Patchwork)Patch Email (Patchwork)Github Pull RequestGithub Pull RequestGithub Pull RequestPatch Email (Patchwork)Github Pull RequestGithub Pull RequestGithub Pull RequestGithub Pull RequestGithub Pull RequestGithub Pull RequestVersion 1.0.a2Version 1.0.b1Version 1.0.0Version 1.1.0Version 1.1.1Version 1.1.2 + + + + + image/svg+xml + + + + + + + + + + + + + + + 1.0ReleaseBranch + + + + + + + + + + Master(Stable) + + + + + + + + + 1.1ReleaseBranch + Version 1.0.a1 + Version 1.1.a1 + Version 1.1.a2 + + + + + Version 1.1.b1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Patch Email (Patchwork) + Github Pull Request + Github Pull Request + Patch Email (Patchwork) + Patch Email (Patchwork) + Github Pull Request + Github Pull Request + Github Pull Request + Patch Email (Patchwork) + Github Pull Request + Github Pull Request + Github Pull Request + Github Pull Request + Github Pull Request + Github Pull Request + + + + + + + + + Version 1.0.a2 + Version 1.0.b1 + Version 1.0.0 + Version 1.1.0 + Version 1.1.1 + Version 1.1.2 + + + + + + + + + + + + + + + + + + -- 2.39.5