From f8c638718b52b24cd7e73f32f5ec7d46f6ee5b62 Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Thu, 12 May 2016 14:47:19 +0200 Subject: [PATCH] core: added contributing file as per github suggestions - to be automatically linked for each on githup pages for contributions --- .github/CONTRIBUTING.md | 147 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000000..fd4d022b78a --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,147 @@ +# Contributing To Kamailio # + +*First, thank you for taking the time to contribute to Kamailio project!* + +The following is a set of guidelines for contributing to Kamailio sources and +documentation. Kamailio source tree is hosted in the [Kamailio Organization](https://github.com/kamailio) on GitHub. + +These are intended to be more like guidelines to keep everything consistent and +coherent, not very strict rules. Use your best judgment and feel free to propose +changes to this document in a pull request. + +### Table Of Contents ### + + * [Overview](#overview) + * [Basic Rules](#basic-rules) + * [Commit Message Format](#commit-message-format) + * [Examples Of Commit Messages](#examples-of-commit-messages) + * [See Also](#see-also) + * [License](#license) + * [License Of New Code Contributions](#license-of-new-code-contributions) + * [Further Assistance](#further-assistance) + +## Overview ## + +Kamailio is a community managed project, with developers world wide. Any +contribution to code or documentation is very welcome and appreciated. + +In order to be easily able to track the changes and have a coherent ChangLog +and commit history, there are several *rules* required for each contribution. + +## Basic Rules ## + + * github pull requests are the favourited mechanism to submit contributions + (patches) + * make a pull request against **master branch** + * commit can be later backported to stable branch(es) + * make a pull request for each new feature + * e.g., if you add a feature to usrloc module and an unrelated feature + to auth module, then make two pull requests + * it is ok (and sometime recommended) to have more than one commit per pull request + * make a commit for each affected component. A component is considered to be: + * the core + * an internal library (code inside subfolder lib/) + * a module (code inside subfolder modules/) + * a tool (code inside subfolder utils/) + * an example or main configs (files inside subfolders etc/ or examples/) + * commit messages **should** be formatted as specified in the next section + * commit message must describe the changes done by the patch + * other details (e.g., how to reproduce, backtrace, sip packets, ...) belong + to content (comments) of the pull request + * avoid emoticons and non-technical statements in commit messages + * e.g., if it was a feature request by John Smith, don't mention that in + commit message, especially don't write it owns you now a beer + * credits can be given within commit message as a short statement, mentioning + the name of the person or entity + * for commits introducing a new module, credits must not be included in the + commit message, being expected that the respective entity will own the + copyright and it is reflected in the README or copyright header of each file + * when the case, make references to the item on bug tracker, using GH #XYZ + -- replace XYZ with issue number id + * e.g.,: - issue reported by John Smith, GH #123 + * changes to **README** file of modules **must** not be done directly in that + file. Instead, edit the xml files located in **modules/modname/doc/** folder + * to regenerate the README, run **make modules-readme modules=modules/modname** + * docbook utils and xsl packages are needed for the above command to work + * it is ok to modify only the xml doc file, the readme can be regenerated by + another developer who has the required tools installed + * if it is a change to README that needs to be backported, make separate + commits to xml doc file and README. The changes to README files are very + likely to rise merge conflicts. With separate commit, that won't be + backported, only the commit to xml doc file, then README will be manually + regenerated in the corresponding branch. + + +## Commit Message Format ## + +Please create the commit messages following the GIT convention: + + * start with one short line, preferably less then 50 chars summarizing the + changes (this is referred later as "first line of the commit message") + * then one empty line + * then a more detailed description + +Think of the first line as of an email "Subject" line. In fact it will be used +as "Subject" in the generated commit emails and it will also be used when +generating the Changelog (e.g. git log --pretty=oneline). + +Please start always with the prefix of the component (subsystem) that is modified by the commit, for example: + * core: typo fixes to log messages + * tcp: stun fixes + * mem: added faster malloc + * module_name: support for foo rfc extension + * lib_name: critical bug fix for abc case + * kamctl: added support for management of module xyz + +### Examples Of Commit Messages ### + + * change to usrloc module from modules + +``` +usrloc: fixed name conflict + +- destroy_avps() renamed to reg_destroy_avps() to avoid conflicts + with the usr_avp.h version +``` + + * change to core + +``` +core: loadpath can now use a list of directories + +- loadpath can use a list of directories separated by ':', + e.g.: loadpath "modules:modules_s:modules_k". + First match wins (e.g. for loadmodule "textops" if + modules/textops.so or modules/textops/textops.so exists, it will + be loaded and the search will stop). +``` + +### See Also ### + + * [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages) + * http://www.tpope.net/node/106 + +The above content about commit message format is taken from Kamailio wiki page: + * https://www.kamailio.org/wiki/devel/git-commit-guidelines + * it is recommended you read that one as well. + +## License ## + +Kamailio Main License: *GPLv2*. + +Each source code file refers to the license and copyright details in the top +of the file. Most of the code is licensed under GPLv2, some parts of the code +are licensed under BSD. + +### License Of New Code Contributions ### + +New contributions to the core and several main modules (auth, corex, sl, tls, +tm) have to be done under the BSD license. New contributions under the GPL must +grant the GPL-OpenSSL linking exception. Contributions to existing components +released under BSD must be done under BSD as well. + +## Further Assistance ### + +For any question, do not hesitate to contact other developers via mailing list: + + * **[sr-dev [at] lists.sip-router.org](http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev)**