CONTRIBUTING.md: note that references to names do not belong to commit messages
[sip-router] / .github / CONTRIBUTING.md
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   * [Contributing Code Or Content](#contributing-code-or-content)
16     * [Basic Rules](#basic-rules)
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)
21       * [See Also](#see-also)
22   * [Reporting Issues](#reporting-issues)
23   * [License](#license)
24     * [License Of New Code Contributions](#license-of-new-code-contributions)
25   * [Further Assistance](#further-assistance)
26
27 ## Overview ##
28
29 Kamailio is a community managed project, with developers world wide. Any
30 contribution to code or documentation is very welcome and appreciated.
31
32 In order to be easily able to track the changes and have a coherent ChangLog
33 and commit history, there are several *rules* required for each contribution.
34
35 ## Contributing Code Or Content ##
36
37 ### Basic Rules ###
38
39   * github pull request is the favorited mechanism to submit contributions
40   (patches)
41   * make a pull request against **master branch**
42     * commit can be later backported to stable branch(es)
43   * make a pull request for each new feature
44     * e.g., if you add a feature to usrloc module and an unrelated feature
45     to auth module, then make two pull requests
46   * it is ok (and sometime recommended) to have more than one commit per pull request
47   * make a commit for each affected component. A component is considered to be:
48     * the core
49     * an internal library (code inside subfolder lib/)
50     * a module (code inside subfolder modules/)
51     * a tool (code inside subfolder utils/)
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
56   file. Instead, edit the xml files located in **modules/modname/doc/** folder
57     * to regenerate the README, run **make modules-readme modules=modules/modname**
58     * docbook utils and xsl packages are needed for the above command to work
59     * it is only necessary to modify and commit the xml doc file, the **README**
60     will be regenerated by a automatic script that is executed every few hours
61     * so if you modify an existing module **README** don't commit the changes
62     of this file to the git repository
63     * if you create a new module that includes also a **README** file, you
64     need to commit the README to the git repository one time
65   * code **should** be formatted with **clang-format** or to match the style of
66   the component that the commit applies to. The `.clang-format` file is part of
67   Kamailio source code tree, in the root folder.
68
69 ### Commit Message Rules ###
70
71 #### Commit Message Format ####
72
73 Please create the commit messages following the GIT convention:
74
75   * start with one short line, preferably less then 50 chars summarizing the
76   changes (this is referred later as "first line of the commit message")
77   * then one empty line
78   * then a more detailed description
79
80 Think of the first line as of an email "Subject" line. In fact it will be used
81 as "Subject" in the generated commit emails and it will also be used when
82 generating the Changelog (e.g. git log --pretty=oneline).
83
84 Please start always with the prefix of the component (subsystem) that is modified by the commit, for example:
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
91   * `kamctl`: added support for management of module xyz
92
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   * 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.
143
144 #### Commit Message Examples ####
145
146   * change to usrloc module from modules
147
148 ```
149 usrloc: fixed name conflict
150
151 - destroy_avps() renamed to reg_destroy_avps() to avoid conflicts
152   with the usr_avp.h version
153 ```
154
155   * change to core
156
157 ```
158 core: loadpath can now use a list of directories
159
160 - loadpath can use a list of directories separated by ':',
161   e.g.: loadpath "modules:modules_s:modules_k".
162   First match wins (e.g. for loadmodule "textops" if
163   modules/textops.so or modules/textops/textops.so exists, it will
164   be loaded and the search will stop).
165 ```
166
167 #### See Also ####
168
169   * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages)
170   * http://www.tpope.net/node/106
171
172 The above content about commit message format is taken from Kamailio wiki page:
173   * https://www.kamailio.org/wiki/devel/git-commit-guidelines
174   * it is recommended you read that one as well.
175
176 ### Developer Access ###
177
178   * developer access (commit rights) to Kamailio GIT repository is granted to
179   people that contribute relevant components (e.g., modules) or have consistent
180   contributions over a long interval of time
181   * each developer has to create an account on github.com portal. The
182   `developerid` is the username on github.com portal
183   * after getting developer access, it is still recommended to use pull request
184   for commits done to other components of Kamailio, to allow the main developer
185   of the component as well as the other developers to review the changes
186   * commits to own components can be pushed directly, without a pull request.
187   However, if the developer wants other people to review the changes, using a
188   pull request is the way to do it
189   * personal branches of developers done inside Kamailio GIT repository must be
190   prefixed with `developerid/`, e.g., `alice/new-feature`. Do not use just
191   `new-feature` or `alice-new-feature` or other variant without `developerid/`
192   * the [Contributions Basic Rules](#basic-rules) from the sections above have
193   to be followed as well after getting developer access
194
195 ## Reporting Issues ##
196
197 Whenever reporting an issue, along with the description of the problems, try to
198 include following details:
199
200   * kamailio version you are using
201     * the output of: **kamailio -v**
202   * the operating system being used
203   * the CPU architecture
204
205 Always useful to have:
206
207   * whenever there is a crash with a corefile, send the backtrace
208     * the output of **bt full** in **gbd**
209   * log messages printed by kamailio in syslog file
210   * *pcap* or *ngrep* capture of SIP packets causing the issue
211   * config file snippets which expose the issues
212
213 Note: replace any sensitive information in the content you add to the issue
214 (e.g., passwords in modparams can be replaced with xyz, each IP address can be
215 replaced with tokens like a.b.c.d, f.g.h.j).
216
217 ## License ##
218
219 Kamailio Main License: *GPLv2*.
220
221 Each source code file refers to the license and copyright details in the top
222 of the file. Most of the code is licensed under GPLv2, some parts of the code
223 are licensed under BSD.
224
225 ### License Of New Code Contributions ###
226
227 New contributions to the core and several main modules (auth, corex, sl, tls,
228 tm) have to be done under the BSD license. New contributions under the GPL must
229 grant the GPL-OpenSSL linking exception. Contributions to existing components
230 released under BSD must be done under BSD as well.
231
232 ## Further Assistance ###
233
234 For any question, do not hesitate to contact other developers via mailing list:
235
236   * **[sr-dev [at] lists.kamailio.org](http://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev)**