Browse code

CONTRIBUTING.md: more content related to commit message format

Daniel-Constantin Mierla authored on 08/10/2020 05:48:28
Showing 1 changed files
... ...
@@ -104,8 +104,15 @@ by the commit, for example:
104 104
   * `modname`: support for foo rfc extension
105 105
     * `usrloc`: support for gruu rfc extension
106 106
   * `lib`: srutils - critical bug fix for abc case
107
+  * `etc`: kamailio.cfg - added core reply route block
108
+  * `misc`: examples/kemi lua - added debug callback function
107 109
   * `kamctl`: added support for management of module xyz
108 110
 
111
+It is acceptable to use slightly different formats, like `etc/kamailio.cfg: ...`
112
+instead of `etc: kamailio.cfg - ...` or `modules/usrloc: ...` instead of
113
+`usrloc: ...`, the important aspect is to indicate the component where the
114
+changes were done.
115
+
109 116
 At the end of the first line some CI flags can be added. Available at this
110 117
 moment:
111 118
 
... ...
@@ -164,7 +171,7 @@ dialplan: basic safety for concurrent rpc reload
164 171
 
165 172
 #### Commit Message Examples ####
166 173
 
167
-  * change to usrloc module from modules
174
+  * changes to usrloc module from modules
168 175
 
169 176
 ```
170 177
 usrloc: fixed name conflict
... ...
@@ -173,7 +180,7 @@ usrloc: fixed name conflict
173 180
   with the usr_avp.h version
174 181
 ```
175 182
 
176
-  * change to core
183
+  * changes to core
177 184
 
178 185
 ```
179 186
 core: loadpath can now use a list of directories
... ...
@@ -183,6 +190,15 @@ core: loadpath can now use a list of directories
183 190
   First match wins (e.g. for loadmodule "textops" if
184 191
   modules/textops.so or modules/textops/textops.so exists, it will
185 192
   be loaded and the search will stop).
193
+```
194
+
195
+  * changes to `etc/kamailio.cfg` file
196
+
197
+```
198
+etc: kamailio.cfg - set load_backends to 1 for permissions module
199
+
200
+- the config uses only address table
201
+
186 202
 ```
187 203
 
188 204
 #### See Also ####
Browse code

.github/CONTRIBUTING.md: link to github docs for pull requests

Daniel-Constantin Mierla authored on 01/10/2020 09:10:01
Showing 1 changed files
... ...
@@ -37,7 +37,10 @@ and commit history, there are several *rules* required for each contribution.
37 37
 ### Basic Rules ###
38 38
 
39 39
   * github pull request is the favorited mechanism to submit contributions
40
-  (patches)
40
+  (patches). See more about at:
41
+    * [Github Docs On Proposing Changes With Pull Requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)
42
+    * the URL to Kamailio project pull requests portal:
43
+    * https://github.com/kamailio/kamailio/pulls
41 44
   * make a pull request against **master branch**
42 45
     * commit can be later backported to stable branch(es)
43 46
   * make a pull request for each new feature
Browse code

github: document precise GPLv2 version that we use in Kamailio (GPLv2 "or later")

Henning Westerholt authored on 08/04/2020 19:55:14
Showing 1 changed files
... ...
@@ -237,8 +237,8 @@ replaced with tokens like a.b.c.d, f.g.h.j).
237 237
 Kamailio Main License: *GPLv2*.
238 238
 
239 239
 Each source code file refers to the license and copyright details in the top
240
-of the file. Most of the code is licensed under GPLv2, some parts of the code
241
-are licensed under BSD.
240
+of the file. Most of the code is licensed under GPLv2 (with the "any later
241
+version" clause), some parts of the code are licensed under BSD.
242 242
 
243 243
 ### License Of New Code Contributions ###
244 244
 
Browse code

CONTRIBUTING.md: small spelling fix after recent doc extension [skip ci]

Henning Westerholt authored on 04/03/2020 19:13:43
Showing 1 changed files
... ...
@@ -90,7 +90,7 @@ as "Subject" in the generated commit emails and it will also be used when
90 90
 generating the Changelog (e.g. git log --pretty=oneline).
91 91
 
92 92
 
93
-The first line (subjecthas to contain meaningful text about what that commit
93
+The first line (subject has to contain meaningful text about what that commit
94 94
 does, do not put just a reference to bug tracker or pull request items
95 95
 
96 96
 Please start always with the prefix of the component (subsystem) that is modified
Browse code

CONTRIBUTING.md: section for first line of the commit message [skip ci]

- note about [skip ci] flag in first line

Daniel-Constantin Mierla authored on 04/03/2020 10:39:02
Showing 1 changed files
... ...
@@ -81,13 +81,20 @@ Please create the commit messages following the GIT convention:
81 81
   * start with one short line, preferably less then 50 chars summarizing the
82 82
   changes (this is referred later as "first line of the commit message")
83 83
   * then one empty line
84
-  * then a more detailed description
84
+  * then a more detailed description (the "commit message content")
85
+
86
+#### First Line Of The Commit Message ####
85 87
 
86 88
 Think of the first line as of an email "Subject" line. In fact it will be used
87 89
 as "Subject" in the generated commit emails and it will also be used when
88 90
 generating the Changelog (e.g. git log --pretty=oneline).
89 91
 
90
-Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
92
+
93
+The first line (subjecthas to contain meaningful text about what that commit
94
+does, do not put just a reference to bug tracker or pull request items
95
+
96
+Please start always with the prefix of the component (subsystem) that is modified
97
+by the commit, for example:
91 98
   * `core`: more fixup helper functions
92 99
     * `core`: tcp - support for haproxy protocol
93 100
     * `core`: mem - added faster malloc
... ...
@@ -96,13 +103,19 @@ Please start always with the prefix of the component (subsystem) that is modifie
96 103
   * `lib`: srutils - critical bug fix for abc case
97 104
   * `kamctl`: added support for management of module xyz
98 105
 
106
+At the end of the first line some CI flags can be added. Available at this
107
+moment:
108
+
109
+  * `[skip ci]` - skip continous integration builds for source code, recommended
110
+  to be added when updating documentation, example configs or other utilities.
111
+  Example:
112
+    * `msilo: docs - updated example for m_dump() function [skip ci]`
113
+
99 114
 #### Commit Message Content ####
100 115
 
101
-  * first line (subject line) has to contain meaningful text about what that commit
102
-  does, do not put just a reference to bug tracker or pull request items
103
-  * commit message must describe the changes done by the patch
116
+* commit message must describe the changes done by the patch
104 117
     * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
105
-    to content (comments) of the pull request. Example:
118
+    to content (comments) of the pull request. Example of a full commit message:
106 119
 ```
107 120
 core: added latency_limit_cfg global parameter
108 121
 
Browse code

github: update CONTRIBUTING guide as decided on the developer meeting

- update CONTRIBUTING guide as decided on the developer meeting
- new introduced functions must be done in native cfg and KEMI
- new introduced module code must be documented in the module docs or wiki

Henning Westerholt authored on 15/11/2019 09:52:01
Showing 1 changed files
... ...
@@ -65,6 +65,12 @@ and commit history, there are several *rules* required for each contribution.
65 65
   * code **should** be formatted with **clang-format** or to match the style of
66 66
   the component that the commit applies to. The `.clang-format` file is part of
67 67
   Kamailio source code tree, in the root folder.
68
+  * new function exports to the configuration **must** be done both as native
69
+  configuration export and KEMI function export.
70
+  * new introduced module parameters, functions and RPC commands **must**
71
+  be documented in the module documentation.
72
+  * new introduced pseudo-variables and transformations **must** be
73
+  documented in the wiki.
68 74
 
69 75
 ### Commit Message Rules ###
70 76
 
Browse code

Revert "github: small additition related to file line endings and windows editors"

- This reverts commit d80bccc3b85256fe0d440cc47c90fc1020ae1d8d.
- not needed anymore, git should take care of this automatically now

Henning Westerholt authored on 09/09/2019 19:35:49
Showing 1 changed files
... ...
@@ -65,8 +65,6 @@ and commit history, there are several *rules* required for each contribution.
65 65
   * code **should** be formatted with **clang-format** or to match the style of
66 66
   the component that the commit applies to. The `.clang-format` file is part of
67 67
   Kamailio source code tree, in the root folder.
68
-  * code **should** be use Linux style line endings and not Windows style
69
-  (CRLF). If you use a Windows editor, please configure it this way.
70 68
 
71 69
 ### Commit Message Rules ###
72 70
 
Browse code

github: small additition related to file line endings and windows editors

Henning Westerholt authored on 08/09/2019 20:57:27
Showing 1 changed files
... ...
@@ -65,6 +65,8 @@ and commit history, there are several *rules* required for each contribution.
65 65
   * code **should** be formatted with **clang-format** or to match the style of
66 66
   the component that the commit applies to. The `.clang-format` file is part of
67 67
   Kamailio source code tree, in the root folder.
68
+  * code **should** be use Linux style line endings and not Windows style
69
+  (CRLF). If you use a Windows editor, please configure it this way.
68 70
 
69 71
 ### Commit Message Rules ###
70 72
 
Browse code

CONTRIBUTING.md: removed garbage bullet from commit mesage details

Daniel-Constantin Mierla authored on 01/09/2019 17:23:08
Showing 1 changed files
... ...
@@ -94,7 +94,6 @@ Please start always with the prefix of the component (subsystem) that is modifie
94 94
 
95 95
   * first line (subject line) has to contain meaningful text about what that commit
96 96
   does, do not put just a reference to bug tracker or pull request items
97
-  * t
98 97
   * commit message must describe the changes done by the patch
99 98
     * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
100 99
     to content (comments) of the pull request. Example:
Browse code

CONTRIBUTING.md: note that references to names do not belong to commit messages

Daniel-Constantin Mierla authored on 13/06/2019 07:40:32
Showing 1 changed files
... ...
@@ -137,6 +137,9 @@ dialplan: basic safety for concurrent rpc reload
137 137
 ```
138 138
 ...: fix for http://private-tracker.lab/1234
139 139
 ```
140
+  * do not mention any developer name or yourself when fixing an issue introduced
141
+  by an old commit done by that developer or you. That commit can be referenced
142
+  by hash id.
140 143
 
141 144
 #### Commit Message Examples ####
142 145
 
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
 
Browse code

github: small syntax fix for contribution guide

Henning Westerholt authored on 10/01/2019 22:27:43
Showing 1 changed files
... ...
@@ -71,7 +71,7 @@ and commit history, there are several *rules* required for each contribution.
71 71
     will be regenerated by a automatic script that is executed every few hours
72 72
     * so if you modify an existing module **README** don't commit the changes
73 73
     of this file to the git repository
74
-    * if you create a new module that includes also a **README file, you
74
+    * if you create a new module that includes also a **README** file, you
75 75
     need to commit the README to the git repository one time
76 76
   * code **should** be formatted with **clang-format** or to match the style of
77 77
   the component that the commit applies to. The `.clang-format` file is part of
Browse code

github: update contribution guidelines about our README file change process

Henning Westerholt authored on 10/01/2019 22:17:00
Showing 1 changed files
... ...
@@ -67,13 +67,12 @@ and commit history, there are several *rules* required for each contribution.
67 67
   file. Instead, edit the xml files located in **modules/modname/doc/** folder
68 68
     * to regenerate the README, run **make modules-readme modules=modules/modname**
69 69
     * docbook utils and xsl packages are needed for the above command to work
70
-    * it is ok to modify only the xml doc file, the readme can be regenerated by
71
-    another developer who has the required tools installed
72
-    * if it is a change to README that needs to be backported, make separate
73
-    commits to xml doc file and README. The changes to README files are very
74
-    likely to rise merge conflicts. With separate commit, that won't be
75
-    backported, only the commit to xml doc file, then README will be manually
76
-    regenerated in the corresponding branch.
70
+    * it is only necessary to modify and commit the xml doc file, the **README**
71
+    will be regenerated by a automatic script that is executed every few hours
72
+    * so if you modify an existing module **README** don't commit the changes
73
+    of this file to the git repository
74
+    * if you create a new module that includes also a **README file, you
75
+    need to commit the README to the git repository one time
77 76
   * code **should** be formatted with **clang-format** or to match the style of
78 77
   the component that the commit applies to. The `.clang-format` file is part of
79 78
   Kamailio source code tree, in the root folder.
Browse code

CONTRIBUTING.md: added developer access section

Daniel-Constantin Mierla authored on 18/02/2018 07:24:36
Showing 1 changed files
... ...
@@ -77,9 +77,6 @@ and commit history, there are several *rules* required for each contribution.
77 77
   * code **should** be formatted with **clang-format** or to match the style of
78 78
   the component that the commit applies to. The `.clang-format` file is part of
79 79
   Kamailio source code tree, in the root folder.
80
-  * personal branches of developers done inside Kamailio GIT repository must be
81
-  prefixed with `developerid/`, e.g., `alice/new-feature`. Do not use just
82
-  `new-feature` or `alice-new-feature` or other variant without `developerid/`.
83 80
 
84 81
 
85 82
 ### Commit Message Format ###
... ...
@@ -135,6 +132,25 @@ The above content about commit message format is taken from Kamailio wiki page:
135 132
   * https://www.kamailio.org/wiki/devel/git-commit-guidelines
136 133
   * it is recommended you read that one as well.
137 134
 
135
+### Developer Access ###
136
+
137
+  * developer access (commit rights) to Kamailio GIT repository is granted to
138
+  people that contribute relevant components (e.g., modules) or have consistent
139
+  contributions over a long interval of time
140
+  * each developer has to create an account on github.com portal. The
141
+  `developerid` is the username on github.com portal
142
+  * after getting developer access, it is still recommended to use pull request
143
+  for commits done to other components of Kamailio, to allow the main developer
144
+  of the component as well as the other developers to review the changes
145
+  * commits to own components can be pushed directly, without a pull request.
146
+  However, if the developer wants other people to review the changes, using a
147
+  pull request is the way to do it
148
+  * personal branches of developers done inside Kamailio GIT repository must be
149
+  prefixed with `developerid/`, e.g., `alice/new-feature`. Do not use just
150
+  `new-feature` or `alice-new-feature` or other variant without `developerid/`
151
+  * the [Contributions Basic Rules](#basic-rules) from the sections above have
152
+  to be followed as well after getting developer access
153
+
138 154
 ## Reporting Issues ##
139 155
 
140 156
 Whenever reporting an issue, along with the description of the problems, try to
Browse code

CONTRIBUTING.md: note about personal branches of developers

- prefix with `developerid/` when creating a personal branch inside
Kamailio GIT repository

Daniel-Constantin Mierla authored on 17/02/2018 19:32:27
Showing 1 changed files
... ...
@@ -77,6 +77,9 @@ and commit history, there are several *rules* required for each contribution.
77 77
   * code **should** be formatted with **clang-format** or to match the style of
78 78
   the component that the commit applies to. The `.clang-format` file is part of
79 79
   Kamailio source code tree, in the root folder.
80
+  * personal branches of developers done inside Kamailio GIT repository must be
81
+  prefixed with `developerid/`, e.g., `alice/new-feature`. Do not use just
82
+  `new-feature` or `alice-new-feature` or other variant without `developerid/`.
80 83
 
81 84
 
82 85
 ### Commit Message Format ###
Browse code

CONTRIBUTING.md: note about formatting the code

- use clang-format or match the style of the existing component

Daniel-Constantin Mierla authored on 09/02/2018 12:52:58
Showing 1 changed files
... ...
@@ -31,6 +31,7 @@ In order to be easily able to track the changes and have a coherent ChangLog
31 31
 and commit history, there are several *rules* required for each contribution.
32 32
 
33 33
 ## Contributing Code Or Content ##
34
+
34 35
 ### Basic Rules ###
35 36
 
36 37
   * github pull requests are the favourited mechanism to submit contributions
... ...
@@ -47,7 +48,7 @@ and commit history, there are several *rules* required for each contribution.
47 48
     * a module (code inside subfolder modules/)
48 49
     * a tool (code inside subfolder utils/)
49 50
     * an example or main configs (files inside subfolders etc/ or examples/)
50
-  * commit messages **should** be formatted as specified in the next section
51
+  * commit messages **has to be formatted** as specified in the next section
51 52
   * commit message must describe the changes done by the patch
52 53
     * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
53 54
     to content (comments) of the pull request
... ...
@@ -73,6 +74,9 @@ and commit history, there are several *rules* required for each contribution.
73 74
     likely to rise merge conflicts. With separate commit, that won't be
74 75
     backported, only the commit to xml doc file, then README will be manually
75 76
     regenerated in the corresponding branch.
77
+  * code **should** be formatted with **clang-format** or to match the style of
78
+  the component that the commit applies to. The `.clang-format` file is part of
79
+  Kamailio source code tree, in the root folder.
76 80
 
77 81
 
78 82
 ### Commit Message Format ###
... ...
@@ -89,12 +93,12 @@ as "Subject" in the generated commit emails and it will also be used when
89 93
 generating the Changelog (e.g. git log --pretty=oneline).
90 94
 
91 95
 Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
92
-  * core: typo fixes to log messages
93
-  * tcp: stun fixes
94
-  * mem: added faster malloc
95
-  * module_name: support for foo rfc extension
96
-  * lib_name: critical bug fix for abc case
97
-  * kamctl: added support for management of module xyz
96
+  * `core`: typo fixes to log messages
97
+  * `tcp`: stun fixes
98
+  * `mem`: added faster malloc
99
+  * `module_name`: support for foo rfc extension
100
+  * `lib_name`: critical bug fix for abc case
101
+  * `kamctl`: added support for management of module xyz
98 102
 
99 103
 #### Examples Of Commit Messages ####
100 104
 
Browse code

core: updated mailing list address in CONTRIBUTING.md

Daniel-Constantin Mierla authored on 16/08/2017 10:33:51 • GitHub committed on 16/08/2017 10:33:51
Showing 1 changed files
... ...
@@ -169,4 +169,4 @@ released under BSD must be done under BSD as well.
169 169
 
170 170
 For any question, do not hesitate to contact other developers via mailing list:
171 171
 
172
-  * **[sr-dev [at] lists.sip-router.org](http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev)**
172
+  * **[sr-dev [at] lists.kamailio.org](http://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev)**
Browse code

core: contribuitions guidelines updated with reporting issues section

Daniel-Constantin Mierla authored on 12/05/2016 13:02:58
Showing 1 changed files
... ...
@@ -12,10 +12,12 @@ changes to this document in a pull request.
12 12
 ### Table Of Contents ###
13 13
 
14 14
   * [Overview](#overview)
15
-  * [Basic Rules](#basic-rules)
16
-  * [Commit Message Format](#commit-message-format)
17
-    * [Examples Of Commit Messages](#examples-of-commit-messages)
18
-    * [See Also](#see-also)
15
+  * [Contributing Code Or Content](#contributing-code-or-content)
16
+    * [Basic Rules](#basic-rules)
17
+    * [Commit Message Format](#commit-message-format)
18
+      * [Examples Of Commit Messages](#examples-of-commit-messages)
19
+      * [See Also](#see-also)
20
+  * [Reporting Issues](#reporting-issues)
19 21
   * [License](#license)
20 22
     * [License Of New Code Contributions](#license-of-new-code-contributions)
21 23
   * [Further Assistance](#further-assistance)
... ...
@@ -28,7 +30,8 @@ contribution to code or documentation is very welcome and appreciated.
28 30
 In order to be easily able to track the changes and have a coherent ChangLog
29 31
 and commit history, there are several *rules* required for each contribution.
30 32
 
31
-## Basic Rules ##
33
+## Contributing Code Or Content ##
34
+### Basic Rules ###
32 35
 
33 36
   * github pull requests are the favourited mechanism to submit contributions
34 37
   (patches)
... ...
@@ -72,7 +75,7 @@ and commit history, there are several *rules* required for each contribution.
72 75
     regenerated in the corresponding branch.
73 76
 
74 77
 
75
-## Commit Message Format ##
78
+### Commit Message Format ###
76 79
 
77 80
 Please create the commit messages following the GIT convention:
78 81
 
... ...
@@ -93,7 +96,7 @@ Please start always with the prefix of the component (subsystem) that is modifie
93 96
   * lib_name: critical bug fix for abc case
94 97
   * kamctl: added support for management of module xyz
95 98
 
96
-### Examples Of Commit Messages ###
99
+#### Examples Of Commit Messages ####
97 100
 
98 101
   * change to usrloc module from modules
99 102
 
... ...
@@ -116,7 +119,7 @@ core: loadpath can now use a list of directories
116 119
   be loaded and the search will stop).
117 120
 ```
118 121
 
119
-### See Also ###
122
+#### See Also ####
120 123
 
121 124
   * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages)
122 125
   * http://www.tpope.net/node/106
... ...
@@ -125,6 +128,28 @@ The above content about commit message format is taken from Kamailio wiki page:
125 128
   * https://www.kamailio.org/wiki/devel/git-commit-guidelines
126 129
   * it is recommended you read that one as well.
127 130
 
131
+## Reporting Issues ##
132
+
133
+Whenever reporting an issue, along with the description of the problems, try to
134
+include following details:
135
+
136
+  * kamailio version you are using
137
+    * the output of: **kamailio -v**
138
+  * the operating system being used
139
+  * the CPU architecture
140
+
141
+Always useful to have:
142
+
143
+  * whenever there is a crash with a corefile, send the backtrace
144
+    * the output of **bt full** in **gbd**
145
+  * log messages printed by kamailio in syslog file
146
+  * *pcap* or *ngrep* capture of SIP packets causing the issue
147
+  * config file snippets which expose the issues
148
+
149
+Note: replace any sensitive information in the content you add to the issue
150
+(e.g., passwords in modparams can be replaced with xyz, each IP address can be
151
+replaced with tokens like a.b.c.d, f.g.h.j).
152
+
128 153
 ## License ##
129 154
 
130 155
 Kamailio Main License: *GPLv2*.
Browse code

core: added contributing file as per github suggestions

- to be automatically linked for each on githup pages for contributions

Daniel-Constantin Mierla authored on 12/05/2016 12:47:19
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,147 @@
1
+# Contributing To Kamailio #
2
+
3
+*First, thank you for taking the time to contribute to Kamailio project!*
4
+
5
+The following is a set of guidelines for contributing to Kamailio sources and
6
+documentation. Kamailio source tree is hosted in the [Kamailio Organization](https://github.com/kamailio) on GitHub.
7
+
8
+These are intended to be more like guidelines to keep everything consistent and
9
+coherent, not very strict rules. Use your best judgment and feel free to propose
10
+changes to this document in a pull request.
11
+
12
+### Table Of Contents ###
13
+
14
+  * [Overview](#overview)
15
+  * [Basic Rules](#basic-rules)
16
+  * [Commit Message Format](#commit-message-format)
17
+    * [Examples Of Commit Messages](#examples-of-commit-messages)
18
+    * [See Also](#see-also)
19
+  * [License](#license)
20
+    * [License Of New Code Contributions](#license-of-new-code-contributions)
21
+  * [Further Assistance](#further-assistance)
22
+
23
+## Overview ##
24
+
25
+Kamailio is a community managed project, with developers world wide. Any
26
+contribution to code or documentation is very welcome and appreciated.
27
+
28
+In order to be easily able to track the changes and have a coherent ChangLog
29
+and commit history, there are several *rules* required for each contribution.
30
+
31
+## Basic Rules ##
32
+
33
+  * github pull requests are the favourited mechanism to submit contributions
34
+  (patches)
35
+  * make a pull request against **master branch**
36
+    * commit can be later backported to stable branch(es)
37
+  * make a pull request for each new feature
38
+    * e.g., if you add a feature to usrloc module and an unrelated feature
39
+    to auth module, then make two pull requests
40
+  * it is ok (and sometime recommended) to have more than one commit per pull request
41
+  * make a commit for each affected component. A component is considered to be:
42
+    * the core
43
+    * an internal library (code inside subfolder lib/)
44
+    * a module (code inside subfolder modules/)
45
+    * a tool (code inside subfolder utils/)
46
+    * an example or main configs (files inside subfolders etc/ or examples/)
47
+  * commit messages **should** be formatted as specified in the next section
48
+  * commit message must describe the changes done by the patch
49
+    * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
50
+    to content (comments) of the pull request
51
+  * avoid emoticons and non-technical statements in commit messages
52
+    * e.g., if it was a feature request by John Smith, don't mention that in
53
+    commit message, especially don't write it owns you now a beer
54
+  * credits can be given within commit message as a short statement, mentioning
55
+  the name of the person or entity
56
+    * for commits introducing a new module, credits must not be included in the
57
+    commit message, being expected that the respective entity will own the
58
+    copyright and it is reflected in the README or copyright header of each file
59
+  * when the case, make references to the item on bug tracker, using GH #XYZ
60
+  -- replace XYZ with issue number id
61
+    * e.g.,: - issue reported by John Smith, GH #123
62
+  * changes to **README** file of modules **must** not be done directly in that
63
+  file. Instead, edit the xml files located in **modules/modname/doc/** folder
64
+    * to regenerate the README, run **make modules-readme modules=modules/modname**
65
+    * docbook utils and xsl packages are needed for the above command to work
66
+    * it is ok to modify only the xml doc file, the readme can be regenerated by
67
+    another developer who has the required tools installed
68
+    * if it is a change to README that needs to be backported, make separate
69
+    commits to xml doc file and README. The changes to README files are very
70
+    likely to rise merge conflicts. With separate commit, that won't be
71
+    backported, only the commit to xml doc file, then README will be manually
72
+    regenerated in the corresponding branch.
73
+
74
+
75
+## Commit Message Format ##
76
+
77
+Please create the commit messages following the GIT convention:
78
+
79
+  * start with one short line, preferably less then 50 chars summarizing the
80
+  changes (this is referred later as "first line of the commit message")
81
+  * then one empty line
82
+  * then a more detailed description
83
+
84
+Think of the first line as of an email "Subject" line. In fact it will be used
85
+as "Subject" in the generated commit emails and it will also be used when
86
+generating the Changelog (e.g. git log --pretty=oneline).
87
+
88
+Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
89
+  * core: typo fixes to log messages
90
+  * tcp: stun fixes
91
+  * mem: added faster malloc
92
+  * module_name: support for foo rfc extension
93
+  * lib_name: critical bug fix for abc case
94
+  * kamctl: added support for management of module xyz
95
+
96
+### Examples Of Commit Messages ###
97
+
98
+  * change to usrloc module from modules
99
+
100
+```
101
+usrloc: fixed name conflict
102
+
103
+- destroy_avps() renamed to reg_destroy_avps() to avoid conflicts
104
+  with the usr_avp.h version
105
+```
106
+
107
+  * change to core
108
+
109
+```
110
+core: loadpath can now use a list of directories
111
+
112
+- loadpath can use a list of directories separated by ':',
113
+  e.g.: loadpath "modules:modules_s:modules_k".
114
+  First match wins (e.g. for loadmodule "textops" if
115
+  modules/textops.so or modules/textops/textops.so exists, it will
116
+  be loaded and the search will stop).
117
+```
118
+
119
+### See Also ###
120
+
121
+  * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages)
122
+  * http://www.tpope.net/node/106
123
+
124
+The above content about commit message format is taken from Kamailio wiki page:
125
+  * https://www.kamailio.org/wiki/devel/git-commit-guidelines
126
+  * it is recommended you read that one as well.
127
+
128
+## License ##
129
+
130
+Kamailio Main License: *GPLv2*.
131
+
132
+Each source code file refers to the license and copyright details in the top
133
+of the file. Most of the code is licensed under GPLv2, some parts of the code
134
+are licensed under BSD.
135
+
136
+### License Of New Code Contributions ###
137
+
138
+New contributions to the core and several main modules (auth, corex, sl, tls,
139
+tm) have to be done under the BSD license. New contributions under the GPL must
140
+grant the GPL-OpenSSL linking exception. Contributions to existing components
141
+released under BSD must be done under BSD as well.
142
+
143
+## Further Assistance ###
144
+
145
+For any question, do not hesitate to contact other developers via mailing list:
146
+
147
+  * **[sr-dev [at] lists.sip-router.org](http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev)**