Browse code

CONTRIBUTING.md: restructured the chapter about commit message rules

- relocated content from basic rules to a dedicated section about commit
message content
- notes that references to non-public resources should not be part of
commit messages
- commits related to code analyzer reports have to describe what was
changed, not be just a referenced to the report

Daniel-Constantin Mierla authored on 22/04/2019 16:50:46
Showing 1 changed files
... ...
@@ -14,8 +14,10 @@ changes to this document in a pull request.
14 14
   * [Overview](#overview)
15 15
   * [Contributing Code Or Content](#contributing-code-or-content)
16 16
     * [Basic Rules](#basic-rules)
17
-    * [Commit Message Format](#commit-message-format)
18
-      * [Examples Of Commit Messages](#examples-of-commit-messages)
17
+    * [Commit Message Rules](#commit-message-rules)
18
+      * [Commit Message Format](#commit-message-format)
19
+      * [Commit Message Content](#commit-message-content)
20
+      * [Commit Message Examples](#commit-message-examples)
19 21
       * [See Also](#see-also)
20 22
   * [Reporting Issues](#reporting-issues)
21 23
   * [License](#license)
... ...
@@ -34,7 +36,7 @@ and commit history, there are several *rules* required for each contribution.
34 36
 
35 37
 ### Basic Rules ###
36 38
 
37
-  * github pull requests are the favourited mechanism to submit contributions
39
+  * github pull request is the favorited mechanism to submit contributions
38 40
   (patches)
39 41
   * make a pull request against **master branch**
40 42
     * commit can be later backported to stable branch(es)
... ...
@@ -47,23 +49,10 @@ and commit history, there are several *rules* required for each contribution.
47 49
     * an internal library (code inside subfolder lib/)
48 50
     * a module (code inside subfolder modules/)
49 51
     * a tool (code inside subfolder utils/)
50
-    * an example or main configs (files inside subfolders etc/ or examples/)
51
-  * commit messages **has to be formatted** as specified in the next section
52
-  * commit message must describe the changes done by the patch
53
-    * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
54
-    to content (comments) of the pull request
55
-  * avoid emoticons and non-technical statements in commit messages
56
-    * e.g., if it was a feature request by John Smith, don't mention that in
57
-    commit message, especially don't write it owns you now a beer
58
-  * credits can be given within commit message as a short statement, mentioning
59
-  the name of the person or entity
60
-    * for commits introducing a new module, credits must not be included in the
61
-    commit message, being expected that the respective entity will own the
62
-    copyright and it is reflected in the README or copyright header of each file
63
-  * when the case, make references to the item on bug tracker, using GH #XYZ
64
-  -- replace XYZ with issue number id
65
-    * e.g.,: - issue reported by John Smith, GH #123
66
-  * changes to **README** file of modules **must** not be done directly in that
52
+    * an example or main configs (files inside subfolders etc/ or misc/examples/)
53
+  * commit message format **has to follow the rules** specified in the next section
54
+  * commit message content **has to follow the rules** specified in the next section 
55
+  * changes to the **README** file of a module **must not** be done directly in that
67 56
   file. Instead, edit the xml files located in **modules/modname/doc/** folder
68 57
     * to regenerate the README, run **make modules-readme modules=modules/modname**
69 58
     * 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.
77 66
   the component that the commit applies to. The `.clang-format` file is part of
78 67
   Kamailio source code tree, in the root folder.
79 68
 
69
+### Commit Message Rules ###
80 70
 
81
-### Commit Message Format ###
71
+#### Commit Message Format ####
82 72
 
83 73
 Please create the commit messages following the GIT convention:
84 74
 
... ...
@@ -92,14 +82,63 @@ as "Subject" in the generated commit emails and it will also be used when
92 82
 generating the Changelog (e.g. git log --pretty=oneline).
93 83
 
94 84
 Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
95
-  * `core`: typo fixes to log messages
96
-  * `tcp`: stun fixes
97
-  * `mem`: added faster malloc
98
-  * `module_name`: support for foo rfc extension
99
-  * `lib_name`: critical bug fix for abc case
85
+  * `core`: more fixup helper functions
86
+    * `core`: tcp - support for haproxy protocol
87
+    * `core`: mem - added faster malloc
88
+  * `modname`: support for foo rfc extension
89
+    * `usrloc`: support for gruu rfc extension
90
+  * `lib`: srutils - critical bug fix for abc case
100 91
   * `kamctl`: added support for management of module xyz
101 92
 
102
-#### Examples Of Commit Messages ####
93
+#### Commit Message Content ####
94
+
95
+  * first line (subject line) has to contain meaningful text about what that commit
96
+  does, do not put just a reference to bug tracker or pull request items
97
+  * t
98
+  * commit message must describe the changes done by the patch
99
+    * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
100
+    to content (comments) of the pull request. Example:
101
+```
102
+core: added latency_limit_cfg global parameter
103
+
104
+- print execution time for configuration script only if it exceeds this value
105
+- default is 0 - print always (behaviour so far)
106
+- it is printed to latency_cfg_log level
107
+```
108
+  * avoid emoticons and non-technical statements in commit messages
109
+    * e.g., if it was a feature request by John Smith, don't mention that in
110
+    commit message, especially don't write it owns you now a beer
111
+  * credits can be given within commit message as a short statement, mentioning
112
+  the name of the person or entity
113
+    * for commits introducing a new module, credits must not be included in the
114
+    commit message, being expected that the respective entity will own the
115
+    copyright and it is reflected in the README or copyright header of each file
116
+  * when the case, make references in the commit body (not in the subject/first line)
117
+  to the items on bug tracker or pull requests, using GH #XYZ
118
+  -- replace XYZ with issue number id. Example:
119
+
120
+```
121
+dialplan: basic safety for concurrent rpc reload
122
+
123
+- reported by GH #1874
124
+```
125
+  * commits related to reports by static analyzers or other tools must describe
126
+  what was fixed or changed. The tool, if a well known one, can be mentioned in
127
+  the body of the commit message, after the technical details presenting the
128
+  changes. For example, do not use commit messages like:
129
+```
130
+...: fix for whatever-tool reports
131
+```
132
+  * do not reference non-public resources (e.g., private links, id of non-public
133
+  static analyzer reports,  ...). For example, do not use commit messages like:
134
+```
135
+...: fix for whatever-tool report #1234
136
+```
137
+```
138
+...: fix for http://private-tracker.lab/1234
139
+```
140
+
141
+#### Commit Message Examples ####
103 142
 
104 143
   * change to usrloc module from modules
105 144