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