@@ -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,63 @@ 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

+```

+

+#### Commit Message Examples ####

   * change to usrloc module from modules