Merge pull request #18657 from Jafaral/commit-msg-format

doc: add commit message guidelines to the dev guide

Author: mjstapp

doc/developer/workflow.rst

@@ -354,15 +354,70 @@ 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
+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.
+
+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 explanation 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 ticks "```" 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
 
-   `Check <https://github.com/FRRouting/frr/tree/master/.github/commitlint.config.js>`_ all
-   the supported subsystems.
+When opening a PR, please follow the same commit message guidelines above. Also
+make sure:
 
-- Commit messages must not end with a period ``.``
+- 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.
+- Make sure that the description you add to the PR is already captured in commits messages.
+  In other words don't leave the commit messages empty. The PR description should just restate
+  or summaries what the the commit messages already have.
 
 Why was my pull request closed?
 -------------------------------