github: small syntax fix for contribution guide
[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
35 ### Basic Rules ###
36
37   * github pull requests are the favourited mechanism to submit contributions
38   (patches)
39   * make a pull request against **master branch**
40     * commit can be later backported to stable branch(es)
41   * make a pull request for each new feature
42     * e.g., if you add a feature to usrloc module and an unrelated feature
43     to auth module, then make two pull requests
44   * it is ok (and sometime recommended) to have more than one commit per pull request
45   * make a commit for each affected component. A component is considered to be:
46     * the core
47     * an internal library (code inside subfolder lib/)
48     * a module (code inside subfolder modules/)
49     * 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
67   file. Instead, edit the xml files located in **modules/modname/doc/** folder
68     * to regenerate the README, run **make modules-readme modules=modules/modname**
69     * docbook utils and xsl packages are needed for the above command to work
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
76   * code **should** be formatted with **clang-format** or to match the style of
77   the component that the commit applies to. The `.clang-format` file is part of
78   Kamailio source code tree, in the root folder.
79
80
81 ### Commit Message Format ###
82
83 Please create the commit messages following the GIT convention:
84
85   * start with one short line, preferably less then 50 chars summarizing the
86   changes (this is referred later as "first line of the commit message")
87   * then one empty line
88   * then a more detailed description
89
90 Think of the first line as of an email "Subject" line. In fact it will be used
91 as "Subject" in the generated commit emails and it will also be used when
92 generating the Changelog (e.g. git log --pretty=oneline).
93
94 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
100   * `kamctl`: added support for management of module xyz
101
102 #### Examples Of Commit Messages ####
103
104   * change to usrloc module from modules
105
106 ```
107 usrloc: fixed name conflict
108
109 - destroy_avps() renamed to reg_destroy_avps() to avoid conflicts
110   with the usr_avp.h version
111 ```
112
113   * change to core
114
115 ```
116 core: loadpath can now use a list of directories
117
118 - loadpath can use a list of directories separated by ':',
119   e.g.: loadpath "modules:modules_s:modules_k".
120   First match wins (e.g. for loadmodule "textops" if
121   modules/textops.so or modules/textops/textops.so exists, it will
122   be loaded and the search will stop).
123 ```
124
125 #### See Also ####
126
127   * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages)
128   * http://www.tpope.net/node/106
129
130 The above content about commit message format is taken from Kamailio wiki page:
131   * https://www.kamailio.org/wiki/devel/git-commit-guidelines
132   * it is recommended you read that one as well.
133
134 ### Developer Access ###
135
136   * developer access (commit rights) to Kamailio GIT repository is granted to
137   people that contribute relevant components (e.g., modules) or have consistent
138   contributions over a long interval of time
139   * each developer has to create an account on github.com portal. The
140   `developerid` is the username on github.com portal
141   * after getting developer access, it is still recommended to use pull request
142   for commits done to other components of Kamailio, to allow the main developer
143   of the component as well as the other developers to review the changes
144   * commits to own components can be pushed directly, without a pull request.
145   However, if the developer wants other people to review the changes, using a
146   pull request is the way to do it
147   * personal branches of developers done inside Kamailio GIT repository must be
148   prefixed with `developerid/`, e.g., `alice/new-feature`. Do not use just
149   `new-feature` or `alice-new-feature` or other variant without `developerid/`
150   * the [Contributions Basic Rules](#basic-rules) from the sections above have
151   to be followed as well after getting developer access
152
153 ## Reporting Issues ##
154
155 Whenever reporting an issue, along with the description of the problems, try to
156 include following details:
157
158   * kamailio version you are using
159     * the output of: **kamailio -v**
160   * the operating system being used
161   * the CPU architecture
162
163 Always useful to have:
164
165   * whenever there is a crash with a corefile, send the backtrace
166     * the output of **bt full** in **gbd**
167   * log messages printed by kamailio in syslog file
168   * *pcap* or *ngrep* capture of SIP packets causing the issue
169   * config file snippets which expose the issues
170
171 Note: replace any sensitive information in the content you add to the issue
172 (e.g., passwords in modparams can be replaced with xyz, each IP address can be
173 replaced with tokens like a.b.c.d, f.g.h.j).
174
175 ## License ##
176
177 Kamailio Main License: *GPLv2*.
178
179 Each source code file refers to the license and copyright details in the top
180 of the file. Most of the code is licensed under GPLv2, some parts of the code
181 are licensed under BSD.
182
183 ### License Of New Code Contributions ###
184
185 New contributions to the core and several main modules (auth, corex, sl, tls,
186 tm) have to be done under the BSD license. New contributions under the GPL must
187 grant the GPL-OpenSSL linking exception. Contributions to existing components
188 released under BSD must be done under BSD as well.
189
190 ## Further Assistance ###
191
192 For any question, do not hesitate to contact other developers via mailing list:
193
194   * **[sr-dev [at] lists.kamailio.org](http://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev)**