diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 227f212fcff..af9c1799fa5 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -14,8 +14,10 @@ changes to this document in a pull request. * [Overview](#overview) * [Contributing Code Or Content](#contributing-code-or-content) * [Basic Rules](#basic-rules) - * [Commit Message Format](#commit-message-format) - * [Examples Of Commit Messages](#examples-of-commit-messages) + * [Commit Message Rules](#commit-message-rules) + * [Commit Message Format](#commit-message-format) + * [Commit Message Content](#commit-message-content) + * [Commit Message Examples](#commit-message-examples) * [See Also](#see-also) * [Reporting Issues](#reporting-issues) * [License](#license) @@ -34,7 +36,7 @@ and commit history, there are several *rules* required for each contribution. ### Basic Rules ### - * github pull requests are the favourited mechanism to submit contributions + * github pull request is the favorited mechanism to submit contributions (patches) * make a pull request against **master branch** * commit can be later backported to stable branch(es) @@ -47,23 +49,10 @@ and commit history, there are several *rules* required for each contribution. * 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 **has to 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 + * an example or main configs (files inside subfolders etc/ or misc/examples/) + * commit message format **has to follow the rules** specified in the next section + * commit message content **has to follow the rules** specified in the next section + * changes to the **README** file of a module **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 @@ -77,8 +66,9 @@ and commit history, there are several *rules* required for each contribution. the component that the commit applies to. The `.clang-format` file is part of Kamailio source code tree, in the root folder. +### Commit Message Rules ### -### Commit Message Format ### +#### Commit Message Format #### Please create the commit messages following the GIT convention: @@ -92,14 +82,63 @@ 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 + * `core`: more fixup helper functions + * `core`: tcp - support for haproxy protocol + * `core`: mem - added faster malloc + * `modname`: support for foo rfc extension + * `usrloc`: support for gruu rfc extension + * `lib`: srutils - critical bug fix for abc case * `kamctl`: added support for management of module xyz -#### Examples Of Commit Messages #### +#### Commit Message Content #### + + * first line (subject line) has to contain meaningful text about what that commit + does, do not put just a reference to bug tracker or pull request items + * t + * 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. Example: +``` +core: added latency_limit_cfg global parameter + +- print execution time for configuration script only if it exceeds this value +- default is 0 - print always (behaviour so far) +- it is printed to latency_cfg_log level +``` + * 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 in the commit body (not in the subject/first line) + to the items on bug tracker or pull requests, using GH #XYZ + -- replace XYZ with issue number id. Example: + +``` +dialplan: basic safety for concurrent rpc reload + +- reported by GH #1874 +``` + * commits related to reports by static analyzers or other tools must describe + what was fixed or changed. The tool, if a well known one, can be mentioned in + the body of the commit message, after the technical details presenting the + changes. For example, do not use commit messages like: +``` +...: fix for whatever-tool reports +``` + * do not reference non-public resources (e.g., private links, id of non-public + static analyzer reports, ...). For example, do not use commit messages like: +``` +...: fix for whatever-tool report #1234 +``` +``` +...: fix for http://private-tracker.lab/1234 +``` + +#### Commit Message Examples #### * change to usrloc module from modules