|
| 1 | +# Reporting a bug |
| 2 | + |
| 3 | +P-KISS-SBC from PyFreeBilling project is an actively maintained project that we constantly strive |
| 4 | +to improve. If you |
| 5 | +think you have discovered a bug, you can help us by submitting an issue in our |
| 6 | +public [issue tracker] by following this guide. |
| 7 | + |
| 8 | + [issue tracker]: https://gitlab.com/mwolff44/pyfreebilling/issues |
| 9 | + |
| 10 | +## Before creating an issue |
| 11 | + |
| 12 | +The maintainers of this project are trying very hard to keep the number of open issues down by |
| 13 | +fixing bugs as fast as possible. By following this guide, you will know exactly |
| 14 | +what information we need to help you quickly. |
| 15 | + |
| 16 | +__But first, please try the following things before creating an issue.__ |
| 17 | + |
| 18 | +### Upgrade to latest version |
| 19 | + |
| 20 | +Chances are that the bug you discovered was already fixed in a subsequent |
| 21 | +version. Thus, before reporting an issue, ensure that you're running the |
| 22 | +[latest version] of P-KISS-SBC. Please consult our [upgrade guide] to |
| 23 | +learn how to upgrade to the latest version. |
| 24 | + |
| 25 | +!!! warning "Bug fixes are not backported" |
| 26 | + |
| 27 | + Please understand that only bugs that occur in the latest version of |
| 28 | + P-KISS-SBC will be addressed. Also, to reduce duplicate efforts, |
| 29 | + fixes cannot be backported to earlier versions. |
| 30 | + |
| 31 | +### Remove customizations |
| 32 | + |
| 33 | +If you're using customizations like Kamailio Modules, container modifications, or |
| 34 | +specific diaplan, please remove them before reporting a bug. |
| 35 | +We can't offer official support for bugs that might hide in your overrides. |
| 36 | + |
| 37 | +If, after removing those settings, the bug is gone, the bug is likely caused by |
| 38 | +your customizations. A good idea is to add them back gradually to narrow down |
| 39 | +the root cause of the problem. If you did a major version upgrade, make sure you |
| 40 | +adjusted all partials you have overridden. |
| 41 | + |
| 42 | +__Don't be shy to ask on our [discussion board] for help if you run into |
| 43 | +problems.__ |
| 44 | + |
| 45 | + [latest version]: ../changelog/index.md |
| 46 | + [upgrade guide]: ../upgrade.md |
| 47 | + [discussion board]: https://gitlab.com/mwolff44/pyfreebilling/discussions |
| 48 | + [StackOverflow]: https://stackoverflow.com |
| 49 | + |
| 50 | + |
| 51 | +### Search for solutions |
| 52 | + |
| 53 | +At this stage, we know that the problem persists in the latest version and is |
| 54 | +not caused by any of your customizations. However, the problem might result from |
| 55 | +a small typo or a syntactical error in a configuration file, e.g., `.env`. |
| 56 | + |
| 57 | +Now, before you go through the trouble of creating a bug report that is answered |
| 58 | +and closed right away with a link to the relevant documentation section or |
| 59 | +another already reported or closed issue or discussion, you can save time for |
| 60 | +us and yourself by doing some research: |
| 61 | + |
| 62 | +1. [Search our documentation] and look for the relevant sections that could |
| 63 | + be related to your problem. If found, make sure that you configured |
| 64 | + everything correctly.[^1] |
| 65 | + |
| 66 | +2. [Search our issue tracker][issue tracker], as another user might already |
| 67 | + have reported the same problem, and there might even be a known workaround |
| 68 | + or fix for it. Thus, no need to create a new issue. |
| 69 | + |
| 70 | +3. [Search our discussion board][discussion board] to learn if other users |
| 71 | + are struggling with similar problems and work together with our great |
| 72 | + community towards a solution. Many problems are solved here. |
| 73 | + |
| 74 | +__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need |
| 75 | +them in the bug report.__[^2] |
| 76 | + |
| 77 | + [^2]: |
| 78 | + We might be using terminology in our documentation different from yours, |
| 79 | + but mean the same. When you include the search terms and related links |
| 80 | + in your bug report, you help us to adjust and improve the documentation. |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +At this point, when you still haven't found a solution to your problem, we |
| 85 | +encourage you to create an issue because it's now very likely that you |
| 86 | +stumbled over something we don't know yet. Read the following section to learn |
| 87 | +how to create a complete and helpful bug report. |
| 88 | + |
| 89 | + [Search our documentation]: ?q= |
| 90 | + |
| 91 | +## Issue template |
| 92 | + |
| 93 | +We have created a new issue template to make the bug reporting process as simple |
| 94 | +as possible and more efficient for the community and us. It |
| 95 | +consists of the following parts: |
| 96 | + |
| 97 | +- [Title] |
| 98 | +- [Context] <small>optional</small> |
| 99 | +- [Description] |
| 100 | +- [Related links] |
| 101 | +- [Steps to reproduce] |
| 102 | +- [Checklist] |
| 103 | + |
| 104 | + [Title]: #title |
| 105 | + [Context]: #context |
| 106 | + [Description]: #description |
| 107 | + [Related links]: #related-links |
| 108 | + [Steps to reproduce]: #steps-to-reproduce |
| 109 | + [Checklist]: #checklist |
| 110 | + |
| 111 | +### Title |
| 112 | + |
| 113 | +A good title is short and descriptive. It should be a one-sentence executive |
| 114 | +summary of the issue, so the impact and severity of the bug you want to report |
| 115 | +can be inferred from the title. |
| 116 | + |
| 117 | +### Context <small>optional</small> { #context } |
| 118 | + |
| 119 | +Before describing the bug, you can provide additional context for us to |
| 120 | +understand what you are trying to achieve. Explain the circumstances |
| 121 | +in which you're using P-KISS-SBC, and what you _think_ might be |
| 122 | +relevant. Don't write about the bug here. |
| 123 | + |
| 124 | +> __Why this might be helpful__: some errors only manifest in specific settings, |
| 125 | +> environments or edge cases, for example, when your documentation contains |
| 126 | +> thousands of documents. |
| 127 | +
|
| 128 | +### Description |
| 129 | + |
| 130 | +Now, to the bug you want to report. Provide a clear, focused, specific, and |
| 131 | +concise summary of the bug you encountered. Explain why you think this is a bug |
| 132 | +that should be reported to P-KISS-SBC. Adhere to the following principles: |
| 133 | + |
| 134 | + |
| 135 | +- __Explain the <u>what</u>, not the <u>how</u>__ – don't explain |
| 136 | + [how to reproduce the bug][Steps to reproduce] here, we're getting there. |
| 137 | + Focus on articulating the problem and its impact as clearly as possible. |
| 138 | + |
| 139 | +- __Keep it short and concise__ – if the bug can be precisely explained in one |
| 140 | + or two sentences, perfect. Don't inflate it – maintainers and future users |
| 141 | + will be grateful for having to read less. |
| 142 | + |
| 143 | +- __One bug at a time__ – if you encounter several unrelated bugs, please |
| 144 | + create separate issues for them. Don't report them in the same issue, as |
| 145 | + this makes attribution difficult. |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix |
| 150 | +the bug, you can help other users temporarily mitigate the problem before |
| 151 | +we maintainers can fix the bug in our code base. |
| 152 | + |
| 153 | +> __Why we need this__: in order for us to understand the problem, we |
| 154 | +> need a clear description of it and quantify its impact, which is essential |
| 155 | +> for triage and prioritization. |
| 156 | +
|
| 157 | +### Related links |
| 158 | + |
| 159 | +Of course, prior to reporting a bug, you have read our documentation and |
| 160 | +[could not find a working solution][search for solutions]. Please share links |
| 161 | +to all sections of our documentation that might be relevant to the bug, as it |
| 162 | +helps us gradually improve it. |
| 163 | + |
| 164 | +Additionally, since you have searched our [issue tracker] and [discussion board] |
| 165 | +before reporting an issue, and have possibly found several issues or |
| 166 | +discussions, include those as well. Every link to an issue or discussion creates |
| 167 | +a backlink, guiding us maintainers and other users in the future. |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +:material-run-fast: __Stretch goal__ – if you also include the search terms you |
| 172 | +used when [searching for a solution][search for solutions] to your problem, you |
| 173 | +make it easier for us maintainers to improve the documentation. |
| 174 | + |
| 175 | +> __Why we need this__: related links help us better understand what you were |
| 176 | +> trying to achieve and whether sections of our documentation need to be |
| 177 | +> adjusted, extended, or overhauled. |
| 178 | +
|
| 179 | + [search for solutions]: #search-for-solutions |
| 180 | + |
| 181 | + |
| 182 | +### Steps to reproduce |
| 183 | + |
| 184 | +At this point, you provided us with enough information to understand the bug. |
| 185 | +However, it might not be immediately apparent how we can see |
| 186 | +the bug in action. |
| 187 | + |
| 188 | +Next, please list the specific steps we should follow to observe the bug. Keep the steps short and concise, and make sure |
| 189 | +not to leave anything out. Use simple language as you would explain it to a |
| 190 | +five-year-old, and focus on continuity. |
| 191 | + |
| 192 | +### Checklist |
| 193 | + |
| 194 | +Thanks for following the guide and creating a high-quality and complete bug |
| 195 | +report – you are almost done. This section ensures that you have read this guide |
| 196 | +and have worked to the best of your knowledge to provide us with everything we |
| 197 | +need to know to help you. |
| 198 | + |
| 199 | +__We'll take it from here.__ |
| 200 | + |
| 201 | +## Incomplete issues |
| 202 | + |
| 203 | +Please understand that we reserve the right to close incomplete issues which |
| 204 | +do not contain minimal reproductions or do not adhere to the quality standards |
| 205 | +and requirements mentioned in this document. Issues can be reopened when the |
| 206 | +missing information has been provided. |
0 commit comments