crm.fsf.org/20131203/files/sites/all/modules-old/civicrm/bower_components/select2/CONTRIBUTING.md

   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]**  &mdash; Check if the issue
  31    has already been reported.
  32 2. **Check if the issue has been fixed**  &mdash; Try to reproduce the problem
  33    using the code in the `master` branch.
  34 3. **Isolate the problem**  &mdash; 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