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