doc: add commit message guidelines to the dev guide

Signed-off-by: Jafar Al-Gharaibeh <[email protected]>

Author: Jafaral

doc/developer/workflow.rst

@@ -354,15 +354,64 @@ This helps to automatically generate human-readable changelog messages.
 Commit Guidelines
 -----------------
 
-There is a built-in commit linter. Basic rules:
+Commit messages must have a title and optionally a detailed description.
 
-- Commit messages must be prefixed with the name of the changed subsystem, followed
-  by a colon and a space and start with an imperative verb.
+The commit title is a short summary of the commit. The following rules apply:
 
+- Must be no more than 72 characters
+- Must be prefixed with the name of the changed subsystem, followed
+  by a colon and a space and start with an imperative verb
    `Check <https://github.com/FRRouting/frr/tree/master/.github/commitlint.config.js>`_ all
    the supported subsystems.
+- Should not end with a period ``.``
+- should be a complete sentence
+- Should "make sense" when used with release changelog.
+- Think of the end-users reading it and write the title to them.
+- FRR maintainers should not need to rewrite the message to explain
+  your work to end-users on your behalf.
 
-- Commit messages must not end with a period ``.``
+Example good commit titles:
+
+.. code-block:: console
+   lib,bgpd: clean up clang warnings
+
+   babeld: convert all code to use our code formatting rules
+
+   doc: add commit message guidelines to the dev guide`
+
+
+The commit description should have more detailed explaination covering also the purpose
+of the work being done. Formatting guidelines include:
+
+- Must be separated from the title by a blank line
+- Must be wrapped to 72 characters, unless it is a sample output
+- Markdown syntax/output code blocks (3 tickes "```" line before and after)
+- Write your commit message in the imperative: "Fix bug" and not "Fixed
+  bug" or "Fixes bug." This convention matches up with commit messages
+  generated by commands like git merge and git revert
+- Bullet points are okay, too
+- Typically a hyphen or asterisk is used for the bullet, followed by a
+  single space. Use a hanging indent
+
+  Example good commit message:
+
+.. code-block:: console
+   pim6d: support embedded-rp
+
+   Implement embedded RP support and configuration commands.
+   Embedded RP is disabled by default and can be globally enabled with the
+   command `embedded-rp` in the PIMv6 configuration node.
+
+   It supports the following options:
+   - Embedded RP maximum limit
+   - Embedded RP group filtering
+
+When opening a PR, please follow the same commit message guidelines above. Also
+make sure:
+- if the PR has a single commit, just copy the commit message as-is to the PR,
+  which is the default behavior for a single commit PR on github.
+- If the PR has more than one commit, add a summary title for the whole PR
+  along with a summary description encompassing all commits.
 
 Why was my pull request closed?
 -------------------------------