CONTRIBUTING.md: note that references to names do not belong to commit messages
[sip-router] / .github / CONTRIBUTING.md
index 227f212..d22cbc0 100644 (file)
@@ -14,8 +14,10 @@ changes to this document in a pull request.
   * [Overview](#overview)
   * [Contributing Code Or Content](#contributing-code-or-content)
     * [Basic Rules](#basic-rules)
-    * [Commit Message Format](#commit-message-format)
-      * [Examples Of Commit Messages](#examples-of-commit-messages)
+    * [Commit Message Rules](#commit-message-rules)
+      * [Commit Message Format](#commit-message-format)
+      * [Commit Message Content](#commit-message-content)
+      * [Commit Message Examples](#commit-message-examples)
       * [See Also](#see-also)
   * [Reporting Issues](#reporting-issues)
   * [License](#license)
@@ -34,7 +36,7 @@ and commit history, there are several *rules* required for each contribution.
 
 ### Basic Rules ###
 
-  * github pull requests are the favourited mechanism to submit contributions
+  * github pull request is the favorited mechanism to submit contributions
   (patches)
   * make a pull request against **master branch**
     * commit can be later backported to stable branch(es)
@@ -47,23 +49,10 @@ and commit history, there are several *rules* required for each contribution.
     * an internal library (code inside subfolder lib/)
     * a module (code inside subfolder modules/)
     * a tool (code inside subfolder utils/)
-    * an example or main configs (files inside subfolders etc/ or examples/)
-  * commit messages **has to be formatted** as specified in the next section
-  * commit message must describe the changes done by the patch
-    * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
-    to content (comments) of the pull request
-  * avoid emoticons and non-technical statements in commit messages
-    * e.g., if it was a feature request by John Smith, don't mention that in
-    commit message, especially don't write it owns you now a beer
-  * credits can be given within commit message as a short statement, mentioning
-  the name of the person or entity
-    * for commits introducing a new module, credits must not be included in the
-    commit message, being expected that the respective entity will own the
-    copyright and it is reflected in the README or copyright header of each file
-  * when the case, make references to the item on bug tracker, using GH #XYZ
-  -- replace XYZ with issue number id
-    * e.g.,: - issue reported by John Smith, GH #123
-  * changes to **README** file of modules **must** not be done directly in that
+    * an example or main configs (files inside subfolders etc/ or misc/examples/)
+  * commit message format **has to follow the rules** specified in the next section
+  * commit message content **has to follow the rules** specified in the next section 
+  * changes to the **README** file of a module **must not** be done directly in that
   file. Instead, edit the xml files located in **modules/modname/doc/** folder
     * to regenerate the README, run **make modules-readme modules=modules/modname**
     * docbook utils and xsl packages are needed for the above command to work
@@ -77,8 +66,9 @@ and commit history, there are several *rules* required for each contribution.
   the component that the commit applies to. The `.clang-format` file is part of
   Kamailio source code tree, in the root folder.
 
+### Commit Message Rules ###
 
-### Commit Message Format ###
+#### Commit Message Format ####
 
 Please create the commit messages following the GIT convention:
 
@@ -92,14 +82,66 @@ as "Subject" in the generated commit emails and it will also be used when
 generating the Changelog (e.g. git log --pretty=oneline).
 
 Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
-  * `core`: typo fixes to log messages
-  * `tcp`: stun fixes
-  * `mem`: added faster malloc
-  * `module_name`: support for foo rfc extension
-  * `lib_name`: critical bug fix for abc case
+  * `core`: more fixup helper functions
+    * `core`: tcp - support for haproxy protocol
+    * `core`: mem - added faster malloc
+  * `modname`: support for foo rfc extension
+    * `usrloc`: support for gruu rfc extension
+  * `lib`: srutils - critical bug fix for abc case
   * `kamctl`: added support for management of module xyz
 
-#### Examples Of Commit Messages ####
+#### Commit Message Content ####
+
+  * first line (subject line) has to contain meaningful text about what that commit
+  does, do not put just a reference to bug tracker or pull request items
+  * t
+  * commit message must describe the changes done by the patch
+    * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
+    to content (comments) of the pull request. Example:
+```
+core: added latency_limit_cfg global parameter
+
+- print execution time for configuration script only if it exceeds this value
+- default is 0 - print always (behaviour so far)
+- it is printed to latency_cfg_log level
+```
+  * avoid emoticons and non-technical statements in commit messages
+    * e.g., if it was a feature request by John Smith, don't mention that in
+    commit message, especially don't write it owns you now a beer
+  * credits can be given within commit message as a short statement, mentioning
+  the name of the person or entity
+    * for commits introducing a new module, credits must not be included in the
+    commit message, being expected that the respective entity will own the
+    copyright and it is reflected in the README or copyright header of each file
+  * when the case, make references in the commit body (not in the subject/first line)
+  to the items on bug tracker or pull requests, using GH #XYZ
+  -- replace XYZ with issue number id. Example:
+
+```
+dialplan: basic safety for concurrent rpc reload
+
+- reported by GH #1874
+```
+  * commits related to reports by static analyzers or other tools must describe
+  what was fixed or changed. The tool, if a well known one, can be mentioned in
+  the body of the commit message, after the technical details presenting the
+  changes. For example, do not use commit messages like:
+```
+...: fix for whatever-tool reports
+```
+  * do not reference non-public resources (e.g., private links, id of non-public
+  static analyzer reports,  ...). For example, do not use commit messages like:
+```
+...: fix for whatever-tool report #1234
+```
+```
+...: fix for http://private-tracker.lab/1234
+```
+  * do not mention any developer name or yourself when fixing an issue introduced
+  by an old commit done by that developer or you. That commit can be referenced
+  by hash id.
+
+#### Commit Message Examples ####
 
   * change to usrloc module from modules