core: updated mailing list address in CONTRIBUTING.md
[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 Format](#commit-message-format)
18       * [Examples Of Commit Messages](#examples-of-commit-messages)
19       * [See Also](#see-also)
20   * [Reporting Issues](#reporting-issues)
21   * [License](#license)
22     * [License Of New Code Contributions](#license-of-new-code-contributions)
23   * [Further Assistance](#further-assistance)
24
25 ## Overview ##
26
27 Kamailio is a community managed project, with developers world wide. Any
28 contribution to code or documentation is very welcome and appreciated.
29
30 In order to be easily able to track the changes and have a coherent ChangLog
31 and commit history, there are several *rules* required for each contribution.
32
33 ## Contributing Code Or Content ##
34 ### Basic Rules ###
35
36   * github pull requests are the favourited mechanism to submit contributions
37   (patches)
38   * make a pull request against **master branch**
39     * commit can be later backported to stable branch(es)
40   * make a pull request for each new feature
41     * e.g., if you add a feature to usrloc module and an unrelated feature
42     to auth module, then make two pull requests
43   * it is ok (and sometime recommended) to have more than one commit per pull request
44   * make a commit for each affected component. A component is considered to be:
45     * the core
46     * an internal library (code inside subfolder lib/)
47     * a module (code inside subfolder modules/)
48     * a tool (code inside subfolder utils/)
49     * 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 message must describe the changes done by the patch
52     * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong
53     to content (comments) of the pull request
54   * avoid emoticons and non-technical statements in commit messages
55     * e.g., if it was a feature request by John Smith, don't mention that in
56     commit message, especially don't write it owns you now a beer
57   * credits can be given within commit message as a short statement, mentioning
58   the name of the person or entity
59     * for commits introducing a new module, credits must not be included in the
60     commit message, being expected that the respective entity will own the
61     copyright and it is reflected in the README or copyright header of each file
62   * when the case, make references to the item on bug tracker, using GH #XYZ
63   -- replace XYZ with issue number id
64     * e.g.,: - issue reported by John Smith, GH #123
65   * changes to **README** file of modules **must** not be done directly in that
66   file. Instead, edit the xml files located in **modules/modname/doc/** folder
67     * to regenerate the README, run **make modules-readme modules=modules/modname**
68     * docbook utils and xsl packages are needed for the above command to work
69     * it is ok to modify only the xml doc file, the readme can be regenerated by
70     another developer who has the required tools installed
71     * if it is a change to README that needs to be backported, make separate
72     commits to xml doc file and README. The changes to README files are very
73     likely to rise merge conflicts. With separate commit, that won't be
74     backported, only the commit to xml doc file, then README will be manually
75     regenerated in the corresponding branch.
76
77
78 ### Commit Message Format ###
79
80 Please create the commit messages following the GIT convention:
81
82   * start with one short line, preferably less then 50 chars summarizing the
83   changes (this is referred later as "first line of the commit message")
84   * then one empty line
85   * then a more detailed description
86
87 Think of the first line as of an email "Subject" line. In fact it will be used
88 as "Subject" in the generated commit emails and it will also be used when
89 generating the Changelog (e.g. git log --pretty=oneline).
90
91 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
98
99 #### Examples Of Commit Messages ####
100
101   * change to usrloc module from modules
102
103 ```
104 usrloc: fixed name conflict
105
106 - destroy_avps() renamed to reg_destroy_avps() to avoid conflicts
107   with the usr_avp.h version
108 ```
109
110   * change to core
111
112 ```
113 core: loadpath can now use a list of directories
114
115 - loadpath can use a list of directories separated by ':',
116   e.g.: loadpath "modules:modules_s:modules_k".
117   First match wins (e.g. for loadmodule "textops" if
118   modules/textops.so or modules/textops/textops.so exists, it will
119   be loaded and the search will stop).
120 ```
121
122 #### See Also ####
123
124   * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages)
125   * http://www.tpope.net/node/106
126
127 The above content about commit message format is taken from Kamailio wiki page:
128   * https://www.kamailio.org/wiki/devel/git-commit-guidelines
129   * it is recommended you read that one as well.
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
153 ## License ##
154
155 Kamailio Main License: *GPLv2*.
156
157 Each source code file refers to the license and copyright details in the top
158 of the file. Most of the code is licensed under GPLv2, some parts of the code
159 are licensed under BSD.
160
161 ### License Of New Code Contributions ###
162
163 New contributions to the core and several main modules (auth, corex, sl, tls,
164 tm) have to be done under the BSD license. New contributions under the GPL must
165 grant the GPL-OpenSSL linking exception. Contributions to existing components
166 released under BSD must be done under BSD as well.
167
168 ## Further Assistance ###
169
170 For any question, do not hesitate to contact other developers via mailing list:
171
172   * **[sr-dev [at] lists.kamailio.org](http://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev)**