Browse Source

Add section to contributing about patches

Kevin Brown 9 years ago
parent
commit
ff4b47bf74
1 changed files with 101 additions and 5 deletions
  1. 101 5
      CONTRIBUTING.md

+ 101 - 5
CONTRIBUTING.md

@@ -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
 time on something which the project developers are not interested in bringing
 into the project.
 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
 Triaging issues and pull requests
 ---------------------------------
 ---------------------------------
 Anyone can help the project maintainers triage issues and review 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.
 under this license **cannot be accepted** into the project.
 
 
 [community]: https://select2.github.io/community.html
 [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
 [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/
 [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
 [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