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)**