1
0
mirror of synced 2025-02-03 21:59:24 +03:00

Add section to contributing about patches

This commit is contained in:
Kevin Brown 2015-09-14 19:11:25 -04:00
parent 4b5743f22e
commit ff4b47bf74

View File

@ -57,6 +57,98 @@ Before starting work on a major feature for Select2, **contact the
time on something which the project developers are not interested in bringing
into the project.
Contributing changes to Select2
-------------------------------
Select2 is made up of multiple submodules that all come together to make the
standard and extended builds that are available to users. The build system uses
Node.js to manage and compile the submodules, all of which is done using the
Grunt build system.
### Installing development dependencies
Select2 can be built and developed on any system which supports Node.js. The
preferred Node.js version is 0.10, but 0.12 and later versions can be used
without any noticeable issues. You can download Node.js at
[their website][nodejs].
All other required Node.js packages can be installed using [npm][npm], which
comes bundled alongside Node.js.
```bash
cd /path/to/select2/repo
npm install
```
You may need to install libsass on your system if it is not already available
in order to build the SASS files which generate the CSS for themes and the main
component.
In order to build and serve the documentation, you need to have [Jekyll][jekyll]
installed on your system.
### Building the Select2 component
Select2 uses the [Grunt][grunt] build task system and defines a few custom
tasks for common routines. One of them is the `compile` task, which compiles
the JavaScript and CSS and produces the final files.
```bash
cd /path/to/select2/repo
grunt compile
```
You can also generate the minified versions (`.min.js` files) by executing the
`minify` task after compiling.
```bash
cd /path/to/select2/repo
grunt minify
```
### Building the documentation
Using the Grunt build system, you run Jekyll and serve the documentation
locally. This will also set up the examples to use the latest version of
Select2 that has been built.
```bash
cd /path/to/select2/repo
grunt docs
```
### Running tests
Select2 uses the QUnit test system to test individual components.
```bash
cd /path/to/selct2/repo
grunt test
```
### Submitting a pull request
We use GitHub's pull request system for submitting patches. Here are some
guidelines to follow when creating the pull request for your fix.
1. Make sure to create a ticket for your pull request. This will serve as the
bug ticket, and any discussion about the bug will take place there. Your pull
request will be focused on the specific changes that fix the bug.
2. Make sure to reference the ticket you are fixing within your pull request.
This will allow us to close off the ticket once we merge the pull request, or
follow up on the ticket if there are any related blocking issues.
3. Explain why the specific change was made. Not everyone who is reviewing your
pull request will be familiar with the problem it is fixing.
4. Run your tests first. If your tests aren't passing, the pull request won't
be able to be merged. If you're breaking existing tests, make sure that you
aren't causing any breaking changes.
5. Only include source changes. While it's not required, only including changes
from the `src` directory will prevent merge conflicts from occuring. Making
this happen can be as a simple as not committing changes from the `dist`
directory.
By following these steps, you will make it easier for your pull request to be
reviewed and eventually merged.
Triaging issues and pull requests
---------------------------------
Anyone can help the project maintainers triage issues and review pull requests.
@ -100,11 +192,15 @@ licensable under the [MIT license][licensing]. Code that cannot be released
under this license **cannot be accepted** into the project.
[community]: https://select2.github.io/community.html
[reporting-bugs]: #reporting-bugs-with-select2
[requesting-features]: #requesting-features-in-select2
[issue-tracker]: https://github.com/select2/select2/issues
[mailing-list]: https://github.com/select2/select2#mailing-list
[grunt]: http://gruntjs.com/
[irc-channel]: https://github.com/select2/select2#irc-channel
[issue-search]: https://github.com/select2/select2/search?q=&type=Issues
[isolated-case]: http://css-tricks.com/6263-reduced-test-cases/
[issue-search]: https://github.com/select2/select2/search?q=&type=Issues
[issue-tracker]: https://github.com/select2/select2/issues
[jekyll]: https://jekyllrb.com/docs/installation/
[licensing]: https://github.com/select2/select2/blob/master/LICENSE.md
[mailing-list]: https://github.com/select2/select2#mailing-list
[nodejs]: https://nodejs.org/
[npm]: https://www.npmjs.com/
[reporting-bugs]: #reporting-bugs-with-select2
[requesting-features]: #requesting-features-in-select2