|
| 1 | +Contributing to yii2-mpdf |
| 2 | +========================= |
| 3 | +Looking to contribute something to yii2-mpdf? **Here's how you can help.** |
| 4 | + |
| 5 | +Please take a moment to review this document in order to make the contribution |
| 6 | +process easy and effective for everyone involved. |
| 7 | + |
| 8 | +Following these guidelines helps to communicate that you respect the time of |
| 9 | +the developers managing and developing this open source project. In return, |
| 10 | +they should reciprocate that respect in addressing your issue or assessing |
| 11 | +patches and features. |
| 12 | + |
| 13 | +Using the issue tracker |
| 14 | +----------------------- |
| 15 | +When [reporting bugs][reporting-bugs] or |
| 16 | +[requesting features][requesting-features], the |
| 17 | +[issue tracker on GitHub][issue-tracker] is the recommended channel to use. |
| 18 | + |
| 19 | +The issue tracker **is not** a place for support requests. Refer the |
| 20 | +[extension documentation](http://demos.krajee.com/mpdf) and/or refer to the |
| 21 | +[webtips Q & A forum](http://webtips.krajee.com/questions) which are the better places to get help. |
| 22 | + |
| 23 | +Reporting bugs with yii2-mpdf |
| 24 | +----------------------------- |
| 25 | +We really appreciate clear bug reports that _consistently_ show an issue |
| 26 | +_within yii2-mpdf_. |
| 27 | + |
| 28 | +The ideal bug report follows these guidelines: |
| 29 | + |
| 30 | +1. **Use the [GitHub issue search][issue-search]** — Check if the issue |
| 31 | + has already been reported. |
| 32 | +2. **Check if the issue has been fixed** — Try to reproduce the problem |
| 33 | + using the code in the `master` branch. |
| 34 | +3. **Isolate the problem** — Try to share a demo or a test case that |
| 35 | + consistently reproduces the problem. |
| 36 | + |
| 37 | +Please try to be as detailed as possible in your bug report, especially if an |
| 38 | +isolated test case cannot be made. Some useful questions to include the answer |
| 39 | +to are: |
| 40 | + |
| 41 | +- What steps can be used to reproduce the issue? |
| 42 | +- What is the bug and what is the expected outcome? |
| 43 | +- What browser(s) and Operating System have you tested with? |
| 44 | +- Does the bug happen consistently across all tested browsers? |
| 45 | +- What version of jQuery are you using? And what version of yii2-mpdf? |
| 46 | +- Are you using yii2-mpdf with other plugins? |
| 47 | + |
| 48 | +All of these questions will help others fix and identify any potential bugs. |
| 49 | + |
| 50 | +Requesting features in yii2-mpdf |
| 51 | +-------------------------------- |
| 52 | +Before starting work on a major feature for yii2-mpdf, **read the |
| 53 | +[documentation](http://demos.krajee.com/mpdf) first** or you may risk spending a considerable amount of |
| 54 | +time on something which the project developers are not interested in bringing into the project. |
| 55 | + |
| 56 | +### Submitting a pull request |
| 57 | + |
| 58 | +We use GitHub's pull request system for submitting patches. Here are some |
| 59 | +guidelines to follow when creating the pull request for your fix. |
| 60 | + |
| 61 | +1. Make sure to create a ticket for your pull request. This will serve as the |
| 62 | +bug ticket, and any discussion about the bug will take place there. Your pull |
| 63 | +request will be focused on the specific changes that fix the bug. |
| 64 | +2. Make sure to reference the ticket you are fixing within your pull request. |
| 65 | +This will allow us to close off the ticket once we merge the pull request, or |
| 66 | +follow up on the ticket if there are any related blocking issues. |
| 67 | +3. Explain why the specific change was made. Not everyone who is reviewing your |
| 68 | +pull request will be familiar with the problem it is fixing. |
| 69 | +4. Run your tests first. If your tests aren't passing, the pull request won't |
| 70 | +be able to be merged. If you're breaking existing tests, make sure that you |
| 71 | +aren't causing any breaking changes. |
| 72 | +5. Only include source changes. While it's not required, only including changes |
| 73 | +from the `src` directory will prevent merge conflicts from occuring. Making |
| 74 | +this happen can be as a simple as not committing changes from the `dist` |
| 75 | +directory. |
| 76 | + |
| 77 | +By following these steps, you will make it easier for your pull request to be |
| 78 | +reviewed and eventually merged. |
| 79 | + |
| 80 | +Triaging issues and pull requests |
| 81 | +--------------------------------- |
| 82 | +Anyone can help the project maintainers triage issues and review pull requests. |
| 83 | + |
| 84 | +### Handling new issues |
| 85 | + |
| 86 | +yii2-mpdf regularly receives new issues which need to be tested and organized. |
| 87 | + |
| 88 | +When a new issue that comes in that is similar to another existing issue, it |
| 89 | +should be checked to make sure it is not a duplicate. Duplicates issues should |
| 90 | +be marked by replying to the issue with "Duplicate of #[issue number]" where |
| 91 | +`[issue number]` is the url or issue number for the existing issue. This will |
| 92 | +allow the project maintainers to quickly close off additional issues and keep |
| 93 | +the discussion focused within a single issue. |
| 94 | + |
| 95 | +If you can test issues that are reported to yii2-mpdf that contain test cases and |
| 96 | +confirm under what conditions bugs happen, that will allow others to identify |
| 97 | +what causes a bug quicker. |
| 98 | + |
| 99 | +### Reviewing pull requests |
| 100 | + |
| 101 | +It is very common for pull requests to be opened for issues that contain a clear |
| 102 | +solution to the problem. These pull requests should be rigorously reviewed by |
| 103 | +the community before being accepted. If you are not sure about a piece of |
| 104 | +submitted code, or know of a better way to do something, do not hesitate to make |
| 105 | +a comment on the pull request. |
| 106 | + |
| 107 | +### Reviving old tickets |
| 108 | + |
| 109 | +If you come across tickets which have not been updated for a while, you are |
| 110 | +encouraged to revive them. While this can be as simple as saying `:+1:`, it is |
| 111 | +best if you can include more information on the issue. Common bugs and feature |
| 112 | +requests are more likely to be fixed, whether it is by the community or the |
| 113 | +developers, so keeping tickets up to date is encouraged. |
| 114 | + |
| 115 | +Licensing |
| 116 | +--------- |
| 117 | + |
| 118 | +It should also be made clear that **all code contributed to yii2-mpdf** must be |
| 119 | +licensable under the [BSD-3 license][licensing]. Code that cannot be released |
| 120 | +under this license **cannot be accepted** into the project. |
| 121 | + |
| 122 | +[issue-search]: https://github.com/kartik-v/yii2-mpdf/search?q=&type=Issues |
| 123 | +[issue-tracker]: https://github.com/kartik-v/yii2-mpdf/issues |
| 124 | +[licensing]: https://github.com/kartik-v/yii2-mpdf/blob/master/LICENSE.md |
| 125 | +[reporting-bugs]: #reporting-bugs-with-yii2-mpdf |
| 126 | +[requesting-features]: #requesting-features-in-yii2-mpdf |
0 commit comments