|
|
@@ -2,20 +2,24 @@ |
|
|
|
|
|
|
|
:tada: First off, thanks for taking the time to contribute! :tada: |
|
|
|
|
|
|
|
The following is a set of guidelines for contributing to Rspamd and its packages, which are hosted in the [Rspamd Organization](https://github.com/rspamd) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. This contribution policy is heavily inspired by [Atom editor](https://github.com/atom/atom). |
|
|
|
The following is a set of guidelines for contributing to Rspamd and its packages, which are hosted in |
|
|
|
the [Rspamd Organization](https://github.com/rspamd) on GitHub. These are mostly guidelines, not rules. Use your best |
|
|
|
judgment, and feel free to propose changes to this document in a pull request. This contribution policy is heavily |
|
|
|
inspired by [Atom editor](https://github.com/atom/atom). |
|
|
|
|
|
|
|
#### Table Of Contents |
|
|
|
|
|
|
|
|
|
|
|
[I don't want to read this whole thing, I just have a question](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) |
|
|
|
|
|
|
|
[How Can I Contribute?](#how-can-i-contribute) |
|
|
|
* [Reporting Bugs](#reporting-bugs) |
|
|
|
|
|
|
|
* [Reporting Bugs](#reporting-bugs) |
|
|
|
|
|
|
|
[Styleguides](#styleguides) |
|
|
|
* [Git Commit Messages](#git-commit-messages) |
|
|
|
* [Lua style guide](#lua-styleguide) |
|
|
|
|
|
|
|
|
|
|
|
* [Git Commit Messages](#git-commit-messages) |
|
|
|
* [Lua style guide](#lua-styleguide) |
|
|
|
|
|
|
|
## I don't want to read this whole thing I just have a question |
|
|
|
|
|
|
|
> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below. |
|
|
@@ -33,25 +37,32 @@ If chat is more your speed, you can join the Rspamd developers and users using T |
|
|
|
|
|
|
|
* [Join Rspamd telegram channel](http://t.me/rspamd) |
|
|
|
* [Join Rspamd IRC channel](https://oftc.net/): |
|
|
|
* server: ircs://irc.oftc.net:6697 |
|
|
|
* channel: #rspamd |
|
|
|
|
|
|
|
Please bear in mind that even though telegram/irc are chat services, sometimes it takes several hours for community members to respond — please be patient! |
|
|
|
* server: ircs://irc.oftc.net:6697 |
|
|
|
* channel: #rspamd |
|
|
|
|
|
|
|
Please bear in mind that even though telegram/irc are chat services, sometimes it takes several hours for community |
|
|
|
members to respond — please be patient! |
|
|
|
|
|
|
|
## How Can I Contribute? |
|
|
|
|
|
|
|
### Reporting Bugs |
|
|
|
|
|
|
|
This section guides you through submitting a bug report for Rspamd. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. |
|
|
|
This section guides you through submitting a bug report for Rspamd. Following these guidelines helps maintainers and the |
|
|
|
community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports : |
|
|
|
mag_right:. |
|
|
|
|
|
|
|
When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out the required template, the information it asks for helps us resolve issues faster. |
|
|
|
When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). |
|
|
|
Fill out the required template, the information it asks for helps us resolve issues faster. |
|
|
|
|
|
|
|
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. |
|
|
|
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new |
|
|
|
> issue and include a link to the original issue in the body of your new one. |
|
|
|
|
|
|
|
#### Before Submitting A Bug Report |
|
|
|
|
|
|
|
* Read about bug reporting in general: https://rspamd.com/doc/faq.html#how-to-report-bugs-found-in-rspamd |
|
|
|
* Enable relevant debugging logs: https://rspamd.com/doc/faq.html#how-to-debug-some-module-in-rspamd |
|
|
|
* Check the FAQs about Core files in case of fatal crash: https://rspamd.com/doc/faq.html#how-to-figure-out-why-rspamd-process-crashed |
|
|
|
* Enable relevant debugging logs: https://rspamd.com/doc/faq.html#how-to-debug-some-module-in-rspamd |
|
|
|
* Check the FAQs about Core files in case of fatal |
|
|
|
crash: https://rspamd.com/doc/faq.html#how-to-figure-out-why-rspamd-process-crashed |
|
|
|
* Check that your issue isn't already filed: https://github.com/issues?utf8=%E2%9C%93&q=is%3Aissue+user%3Arspamd |
|
|
|
* Check that there is not already an experimental package or master branch |
|
|
|
|
|
|
@@ -60,25 +71,39 @@ When you are creating a bug report, please [include as many details as possible] |
|
|
|
Explain the problem and include additional details to help maintainers reproduce the problem: |
|
|
|
|
|
|
|
* **Use a clear and descriptive title** for the issue to identify the problem. |
|
|
|
* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining how you started Rspamd, e.g. which custom configuration are you using, or what message have you scanned. When listing steps, **don't just say what you did, but explain how you did it**. |
|
|
|
* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). |
|
|
|
* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. |
|
|
|
* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by |
|
|
|
explaining how you started Rspamd, e.g. which custom configuration are you using, or what message have you scanned. |
|
|
|
When listing steps, **don't just say what you did, but explain how you did it**. |
|
|
|
* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable |
|
|
|
snippets, which you use in those examples. If you're providing snippets in the issue, |
|
|
|
use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). |
|
|
|
* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that |
|
|
|
behavior. |
|
|
|
* **Explain which behavior you expected to see instead and why.** |
|
|
|
* **If you're reporting that Rspamd crashed**, include a crash report with a stack trace from the operating system: https://rspamd.com/doc/faq.html#how-to-figure-out-why-rspamd-process-crashed |
|
|
|
* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below. |
|
|
|
* **If you're reporting that Rspamd crashed**, include a crash report with a stack trace from the operating |
|
|
|
system: https://rspamd.com/doc/faq.html#how-to-figure-out-why-rspamd-process-crashed |
|
|
|
* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and |
|
|
|
share more information using the guidelines below. |
|
|
|
|
|
|
|
Provide more context by answering these questions: |
|
|
|
|
|
|
|
* **Did the problem start happening recently** (e.g. after updating to a new version of Rspamd) or was this always a problem? |
|
|
|
* If the problem started happening recently, **can you reproduce the problem in an older version of Rspamd?** What's the most recent version in which the problem doesn't happen? You can download older versions of Rspamd from [the releases page](https://github.com/rspamd/rspamd/releases). |
|
|
|
* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. |
|
|
|
* If the problem is related to scanning messages, **does the problem happen for all messages or only some?** |
|
|
|
* **Did the problem start happening recently** (e.g. after updating to a new version of Rspamd) or was this always a |
|
|
|
problem? |
|
|
|
* If the problem started happening recently, **can you reproduce the problem in an older version of Rspamd?** What's the |
|
|
|
most recent version in which the problem doesn't happen? You can download older versions of Rspamd |
|
|
|
from [the releases page](https://github.com/rspamd/rspamd/releases). |
|
|
|
* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which |
|
|
|
conditions it normally happens. |
|
|
|
* If the problem is related to scanning messages, **does the problem happen for all messages or only some?** |
|
|
|
|
|
|
|
Include details about your configuration and environment: |
|
|
|
|
|
|
|
* **Which version of Rspamd are you using?** Use `rspamd --version` to get the detailed information about the version and the compile flags used. |
|
|
|
* **Which version of Rspamd are you using?** Use `rspamd --version` to get the detailed information about the version |
|
|
|
and the compile flags used. |
|
|
|
* **What's the name and version of the OS you're using**? |
|
|
|
* **What hardware are you using, including CPU generation**, e.g. Intel Haswell or ArmV7? If you have `gcc` installed, that could be achieved by the following command: `gcc -march=native -Q --help=target|grep march`. In Linux, you can also check `/proc/cpuinfo` file for the required details. |
|
|
|
* **What hardware are you using, including CPU generation**, e.g. Intel Haswell or ArmV7? If you have `gcc` installed, |
|
|
|
that could be achieved by the following command: `gcc -march=native -Q --help=target|grep march`. In Linux, you can |
|
|
|
also check `/proc/cpuinfo` file for the required details. |
|
|
|
|
|
|
|
## Styleguides |
|
|
|
|
|
|
@@ -94,9 +119,10 @@ Include details about your configuration and environment: |
|
|
|
* [Fix] - bug fix |
|
|
|
* [CritFix] - critical bug fix worth a new version releasing |
|
|
|
* [Rework] - some significant logic rework |
|
|
|
* [Config] - configuration change |
|
|
|
* [Conf] - configuration change |
|
|
|
* [Rules] - rules change |
|
|
|
|
|
|
|
|
|
|
|
### Lua styleguide |
|
|
|
|
|
|
|
Please use the following [Lua style guide](lua_style.md) when contributing changes to Lua code. This guide is both applicable for rules, libraries and plugins. |
|
|
|
Please use the following [Lua style guide](lua_style.md) when contributing changes to Lua code. This guide is both |
|
|
|
applicable for rules, libraries and plugins. |