Pārlūkot izejas kodu

Add section to contributing about patches

Kevin Brown 9 gadi atpakaļ
vecāks
revīzija
ff4b47bf74
1 mainītis faili ar 101 papildinājumiem un 5 dzēšanām
  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
 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