|
| 1 | +<!-- omit in toc --> |
| 2 | + |
| 3 | +# Contributing to django-tasks-scheduler |
| 4 | + |
| 5 | +First off, thanks for taking the time to contribute! ❤️ |
| 6 | + |
| 7 | +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways |
| 8 | +to help and details about how this project handles them. Please make sure to read the relevant section before making |
| 9 | +your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The |
| 10 | +community looks forward to your contributions. 🎉 |
| 11 | + |
| 12 | +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support |
| 13 | +> the project and show your appreciation, which we would also be very happy about: |
| 14 | +> - Star the project |
| 15 | +> - Tweet about it |
| 16 | +> - Refer this project in your project's readme |
| 17 | +> - Mention the project at local meetups and tell your friends/colleagues |
| 18 | +
|
| 19 | +<!-- omit in toc --> |
| 20 | + |
| 21 | +## Table of Contents |
| 22 | + |
| 23 | +- [Code of Conduct](#code-of-conduct) |
| 24 | +- [I Have a Question](#i-have-a-question) |
| 25 | +- [I Want To Contribute](#i-want-to-contribute) |
| 26 | + - [Reporting Bugs](#reporting-bugs) |
| 27 | + - [Suggesting Enhancements](#suggesting-enhancements) |
| 28 | + - [Your First Code Contribution](#your-first-code-contribution) |
| 29 | + - [Improving The Documentation](#improving-the-documentation) |
| 30 | +- [Style guides](#style-guides) |
| 31 | + - [Commit Messages](#commit-messages) |
| 32 | +- [Join The Project Team](#join-the-project-team) |
| 33 | + |
| 34 | +## Code of Conduct |
| 35 | + |
| 36 | +This project and everyone participating in it is governed by the |
| 37 | +[django-tasks-scheduler Code of Conduct](https://github.com/dsoftwareinc/django-tasks-scheduler/blob/main/CODE_OF_CONDUCT.md). |
| 38 | +By participating, you are expected to uphold this code. Please report unacceptable behavior |
| 39 | + |
| 40 | + |
| 41 | +## I Have a Question |
| 42 | + |
| 43 | +> If you want to ask a question, we assume that you have read the |
| 44 | +> available [Documentation](https://github.com/dsoftwareinc/django-tasks-scheduler). |
| 45 | +
|
| 46 | +Before you ask a question, it is best to search for |
| 47 | +existing [Issues](https://github.com/dsoftwareinc/django-tasks-scheduler/issues) that might help you. In case you have |
| 48 | +found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to |
| 49 | +search the internet for answers first. |
| 50 | + |
| 51 | +If you then still feel the need to ask a question and need clarification, we recommend the following: |
| 52 | + |
| 53 | +- Open an [Issue](https://github.com/dsoftwareinc/django-tasks-scheduler/issues/new). |
| 54 | +- Provide as much context as you can about what you're running into. |
| 55 | +- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant. |
| 56 | + |
| 57 | +We will then take care of the issue as soon as possible. |
| 58 | + |
| 59 | +<!-- |
| 60 | +You might want to create a separate issue tag for questions and include it in this description. People should then tag their issues accordingly. |
| 61 | +
|
| 62 | +Depending on how large the project is, you may want to outsource the questioning, e.g. to Stack Overflow or Gitter. You may add additional contact and information possibilities: |
| 63 | +- IRC |
| 64 | +- Slack |
| 65 | +- Gitter |
| 66 | +- Stack Overflow tag |
| 67 | +- Blog |
| 68 | +- FAQ |
| 69 | +- Roadmap |
| 70 | +- E-Mail List |
| 71 | +- Forum |
| 72 | +--> |
| 73 | + |
| 74 | +## I Want To Contribute |
| 75 | + |
| 76 | +> ### Legal Notice <!-- omit in toc --> |
| 77 | +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the |
| 78 | +> necessary rights to the content and that the content you contribute may be provided under the project license. |
| 79 | +
|
| 80 | +### Reporting Bugs |
| 81 | + |
| 82 | +<!-- omit in toc --> |
| 83 | + |
| 84 | +#### Before Submitting a Bug Report |
| 85 | + |
| 86 | +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to |
| 87 | +investigate carefully, collect information and describe the issue in detail in your report. Please complete the |
| 88 | +following steps in advance to help us fix any potential bug as fast as possible. |
| 89 | + |
| 90 | +- Make sure that you are using the latest version. |
| 91 | +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment |
| 92 | + components/versions (Make sure that you have read |
| 93 | + the [documentation](https://github.com/dsoftwareinc/django-tasks-scheduler). If you are looking for support, you might |
| 94 | + want to check [this section](#i-have-a-question)). |
| 95 | +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there |
| 96 | + is not already a bug report existing for your bug or error in |
| 97 | + the [bug tracker](https://github.com/dsoftwareinc/django-tasks-scheduler/issues?q=label%3Abug). |
| 98 | +- Also make sure to search the internet (including Stack Overflow) to see if users outside the GitHub community have |
| 99 | + discussed the issue. |
| 100 | +- Collect information about the bug: |
| 101 | + - Stack trace (Traceback) |
| 102 | + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) |
| 103 | + - Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. |
| 104 | + - Possibly your input and the output |
| 105 | + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? |
| 106 | + |
| 107 | +<!-- omit in toc --> |
| 108 | + |
| 109 | +#### How Do I Submit a Good Bug Report? |
| 110 | + |
| 111 | +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue |
| 112 | +> tracker, or elsewhere in public. Instead, sensitive bugs must be sent by email to <[email protected]>. |
| 113 | +<!-- You may add a PGP key to allow the messages to be sent encrypted as well. --> |
| 114 | +
|
| 115 | +We use GitHub issues to track bugs and errors. If you run into an issue with the project: |
| 116 | + |
| 117 | +- Open an [Issue](https://github.com/dsoftwareinc/django-tasks-scheduler/issues/new). (Since we can't be sure at this point |
| 118 | + whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) |
| 119 | +- Explain the behavior you would expect and the actual behavior. |
| 120 | +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to |
| 121 | + recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem |
| 122 | + and create a reduced test case. |
| 123 | +- Provide the information you collected in the previous section. |
| 124 | + |
| 125 | +Once it's filed: |
| 126 | + |
| 127 | +- The project team will label the issue accordingly. |
| 128 | +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no |
| 129 | + obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs |
| 130 | + with the `needs-repro` tag will not be addressed until they are reproduced. |
| 131 | +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such |
| 132 | + as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). |
| 133 | + |
| 134 | +<!-- You might want to create an issue template for bugs and errors that can be used as a guide and that defines the structure of the information to be included. If you do so, reference it here in the description. --> |
| 135 | + |
| 136 | +### Suggesting Enhancements |
| 137 | + |
| 138 | +This section guides you through submitting an enhancement suggestion for django-tasks-scheduler, **including completely new |
| 139 | +features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the |
| 140 | +community to understand your suggestion and find related suggestions. |
| 141 | + |
| 142 | +<!-- omit in toc --> |
| 143 | + |
| 144 | +#### Before Submitting an Enhancement |
| 145 | + |
| 146 | +- Make sure that you are using the latest version. |
| 147 | +- Read the [documentation](https://github.com/dsoftwareinc/django-tasks-scheduler) carefully and find out if the |
| 148 | + functionality is already covered, maybe by an individual configuration. |
| 149 | +- Perform a [search](https://github.com/dsoftwareinc/django-tasks-scheduler/issues) to see if the enhancement has already |
| 150 | + been suggested. If it has, add a comment to the existing issue instead of opening a new one. |
| 151 | +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to |
| 152 | + convince the project's developers of the merits of this feature. Keep in mind that we want features that will be |
| 153 | + useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, |
| 154 | + consider writing an add-on/plugin library. |
| 155 | + |
| 156 | +<!-- omit in toc --> |
| 157 | + |
| 158 | +#### How Do I Submit a Good Enhancement Suggestion? |
| 159 | + |
| 160 | +Enhancement suggestions are tracked as [GitHub issues](https://github.com/dsoftwareinc/django-tasks-scheduler/issues). |
| 161 | + |
| 162 | +- Use a **clear and descriptive title** for the issue to identify the suggestion. |
| 163 | +- Provide a **step-by-step description of the suggested enhancement** in as many details as possible. |
| 164 | +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point |
| 165 | + you can also tell which alternatives do not work for you. |
| 166 | +- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part |
| 167 | + which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS |
| 168 | + and Windows, and [this tool](https://github.com/colinkeenan/silentcast) |
| 169 | + or [this tool](https://github.com/GNOME/byzanz) on |
| 170 | + Linux. <!-- this should only be included if the project has a GUI --> |
| 171 | +- **Explain why this enhancement would be useful** to most django-tasks-scheduler users. You may also want to point out the |
| 172 | + other projects that solved it better and which could serve as inspiration. |
| 173 | + |
| 174 | +<!-- You might want to create an issue template for enhancement suggestions that can be used as a guide and that defines the structure of the information to be included. If you do so, reference it here in the description. --> |
| 175 | + |
| 176 | +### Your First Code Contribution |
| 177 | + |
| 178 | +<!-- TODO |
| 179 | +include Setup of env, IDE and typical getting started instructions? |
| 180 | +
|
| 181 | +--> |
| 182 | + |
| 183 | +### Improving The Documentation |
| 184 | + |
| 185 | +<!-- TODO |
| 186 | +Updating, improving and correcting the documentation |
| 187 | +
|
| 188 | +--> |
| 189 | + |
| 190 | +## Style guides |
| 191 | + |
| 192 | +### Commit Messages |
| 193 | + |
| 194 | +Taken from [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) |
| 195 | + |
| 196 | +``` |
| 197 | +<type>[optional scope]: <description> |
| 198 | +
|
| 199 | +[optional body] |
| 200 | +
|
| 201 | +[optional footer(s)] |
| 202 | +``` |
| 203 | + |
| 204 | +The commit contains the following structural elements, to communicate intent to the consumers of your library: |
| 205 | + |
| 206 | +* `fix:` a commit of the type fix patches a bug in your codebase (this correlates with `PATCH` in Semantic Versioning). |
| 207 | +* `feat:` a commit of the type feat introduces a new feature to the codebase (this correlates with `MINOR` in Semantic |
| 208 | + Versioning). |
| 209 | +* `BREAKING CHANGE:` a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a |
| 210 | + breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any |
| 211 | + type. |
| 212 | +* types other than `fix:` and `feat:` are allowed, for example @commitlint/config-conventional (based on the Angular |
| 213 | + convention) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others. |
| 214 | +* footers other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to |
| 215 | + [git trailer format](https://git-scm.com/docs/git-interpret-trailers). |
| 216 | + |
| 217 | +Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic |
| 218 | +Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit’s type, to provide additional |
| 219 | +contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays. |
| 220 | + |
| 221 | +## Join The Project Team |
| 222 | + |
| 223 | +<!-- TODO --> |
| 224 | + |
| 225 | +<!-- omit in toc --> |
| 226 | + |
| 227 | +## Attribution |
| 228 | + |
| 229 | +This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! |
0 commit comments