1
|
Contributing to Select2
|
2
|
=======================
|
3
|
Looking to contribute something to Select2? **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. The
|
20
|
[mailing list][mailing-list] or [IRC channel][irc-channel] are better places to
|
21
|
get help.
|
22
|
|
23
|
Reporting bugs with Select2
|
24
|
---------------------------
|
25
|
We really appreciate clear bug reports that _consistently_ show an issue
|
26
|
_within Select2_.
|
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 create an
|
35
|
[isolated test case][isolated-case] that 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 Select2?
|
46
|
- Are you using Select2 with other plugins?
|
47
|
|
48
|
All of these questions will help people fix and identify any potential bugs.
|
49
|
|
50
|
Requesting features in Select2
|
51
|
------------------------------
|
52
|
Select2 is a large library that carries with it a lot of functionality. Because
|
53
|
of this, many feature requests will not be implemented in the core library.
|
54
|
|
55
|
Before starting work on a major feature for Select2, **contact the
|
56
|
[community][community] first** or you may risk spending a considerable amount of
|
57
|
time on something which the project developers are not interested in bringing
|
58
|
into the project.
|
59
|
|
60
|
### Select2 4.0
|
61
|
|
62
|
Many feature requests will be closed off until 4.0, where Select2 plans to adopt
|
63
|
a more flexible API. If you are interested in helping with the development of
|
64
|
the next major Select2 release, please send a message to the
|
65
|
[mailing list][mailing-list] or [irc channel][irc-channel] for more information.
|
66
|
|
67
|
Triaging issues and pull requests
|
68
|
---------------------------------
|
69
|
Anyone can help the project maintainers triage issues and review pull requests.
|
70
|
|
71
|
### Handling new issues
|
72
|
|
73
|
Select2 regularly receives new issues which need to be tested and organized.
|
74
|
|
75
|
When a new issue that comes in that is similar to another existing issue, it
|
76
|
should be checked to make sure it is not a duplicate. Duplicates issues should
|
77
|
be marked by replying to the issue with "Duplicate of #[issue number]" where
|
78
|
`[issue number]` is the url or issue number for the existing issue. This will
|
79
|
allow the project maintainers to quickly close off additional issues and keep
|
80
|
the discussion focused within a single issue.
|
81
|
|
82
|
If you can test issues that are reported to Select2 that contain test cases and
|
83
|
confirm under what conditions bugs happen, that will allow others to identify
|
84
|
what causes a bug quicker.
|
85
|
|
86
|
### Reviewing pull requests
|
87
|
|
88
|
It is very common for pull requests to be opened for issues that contain a clear
|
89
|
solution to the problem. These pull requests should be rigorously reviewed by
|
90
|
the community before being accepted. If you are not sure about a piece of
|
91
|
submitted code, or know of a better way to do something, do not hesitate to make
|
92
|
a comment on the pull request.
|
93
|
|
94
|
It should also be made clear that **all code contributed to Select** must be
|
95
|
licensable under the [Apache 2 or GPL 2 licenses][licensing]. Code that cannot
|
96
|
be released under either of these licenses **cannot be accepted** into the
|
97
|
project.
|
98
|
|
99
|
[community]: https://github.com/ivaynberg/select2#community
|
100
|
[reporting-bugs]: #reporting-bugs-with-select2
|
101
|
[requesting-features]: #requesting-features-in-select2
|
102
|
[issue-tracker]: https://github.com/ivaynberg/select2/issues
|
103
|
[mailing-list]: https://github.com/ivaynberg/select2#mailing-list
|
104
|
[irc-channel]: https://github.com/ivaynberg/select2#irc-channel
|
105
|
[issue-search]: https://github.com/ivaynberg/select2/search?q=&type=Issues
|
106
|
[isolated-case]: http://css-tricks.com/6263-reduced-test-cases/
|
107
|
[licensing]: https://github.com/ivaynberg/select2#copyright-and-license
|