library-mirrors/jquery
1
0
Fork 0
mirror of https://github.com/jquery/jquery.git synced 2024-11-23 02:54:22 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

CONTRIBUTING: Condense info and add directions to other resources

Browse Source 
Fixes gh-1824
(cherry picked from commit bfd5dab2c6)

Conflicts:
	CONTRIBUTING.md
This commit is contained in:
Dave Methvin 2014-12-03 19:07:48 -05:00
parent a90ff8c8c7
commit 404d2aa269
1 changed files with 23 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
CONTRIBUTING.md
View File

@ -1,85 +1,65 @@
# Contributing to jQuery
1. [Getting Involved](#getting-involved)
2. [Discussion](#discussion)
2. [Questions and Discussion](#questions-and-discussion)
3. [How To Report Bugs](#how-to-report-bugs)
4. [Core Style Guide](#jquery-core-style-guide)
5. [Tips For Bug Patching](#tips-for-bug-patching)
4. [Tips for Bug Patching](#tips-for-bug-patching)
Note: This is the code development repository for *jQuery Core* only. Before opening an issue or making a pull request, be sure you're in the right place.
* jQuery plugin issues should be reported to the author of the plugin.
* jQuery Core API documentation issues can be filed [at the API repo](http://github.com/jquery/api.jquery.com/issues).
* Bugs or suggestions for other jQuery Foundation projects should be filed in [their respective repos](http://github.com/jquery/).
## Getting Involved
There are a number of ways to get involved with the development of jQuery core. Even if you've never contributed code to an Open Source project before, we're always looking for help identifying bugs, writing and reducing test cases and documentation.
We've put together [a short guide with tips, tricks, and ideas on getting started](http://contribute.jquery.org/open-source/). We're always looking for help identifying bugs, writing and reducing test cases, and documentation.
This is the best way to contribute to jQuery core. Please read through the full guide detailing [How to Report Bugs](#how-to-report-bugs).
More information on how to contribute to this and other jQuery Foundation projects is at [contribute.jquery.org](http://contribute.jquery.org). Please review our [commit & pull request guide](http://contribute.jquery.org/commits-and-pull-requests/) and [style guides](http://contribute.jquery.org/style-guide/) for instructions on how to maintain a fork and submit patches. Before we can merge any pull request, we'll also need you to sign our [contributor license agreement](http://contribute.jquery.org/cla/).
## Discussion
## Questions and Discussion
### Forum and IRC
The jQuery core development team frequently tracks posts on the [jQuery Development Forum](http://forum.jquery.com/developing-jquery-core). If you have longer posts or questions please feel free to post them there. If you think you've found a bug please [file it in the bug tracker](#how-to-report-bugs).
jQuery is so popular that many developers have knowledge of its capabilities and limitations. Most questions about using jQuery can be answered on popular forums such as [Stack Overflow](http://stackoverflow.com). Please start there when you have questions, even if you think you've found a bug.
Additionally most of the jQuery core development team can be found in the [#jquery-dev](http://webchat.freenode.net/?channels=jquery-dev) IRC channel on irc.freenode.net.
The jQuery Core team watches the [jQuery Development Forum](http://forum.jquery.com/developing-jquery-core). If you have longer posts or questions that can't be answered in places such as Stack Overflow, please feel free to post them there. If you think you've found a bug, please [file it in the bug tracker](#how-to-report-bugs). The Core team can be found in the [#jquery-dev](http://webchat.freenode.net/?channels=jquery-dev) IRC channel on irc.freenode.net.
### Weekly Status Meetings
Every week (unless otherwise noted) the jQuery core dev team has a meeting to discuss the progress of current work and to bring forward possible new blocker bugs for discussion.
The jQuery Core team has a weekly meeting to discuss the progress of current work. The meeting is held in the [#jquery-meeting](http://webchat.freenode.net/?channels=jquery-meeting) IRC channel on irc.freenode.net at [Noon EST](http://www.timeanddate.com/worldclock/fixedtime.html?month=1&day=17&year=2011&hour=12&min=0&sec=0&p1=43) on Mondays.
The meeting is held in the [#jquery-meeting](http://webchat.freenode.net/?channels=jquery-meeting) IRC channel on irc.freenode.net at [Noon EST](http://www.timeanddate.com/worldclock/fixedtime.html?month=1&day=17&year=2011&hour=12&min=0&sec=0&p1=43) on Mondays.
[Past Meeting Notes](https://docs.google.com/document/d/1MrLFvoxW7GMlH9KK-bwypn77cC98jUnz7sMW1rg_TP4/edit?hl=en)
[jQuery Core Meeting Notes](http://meetings.jquery.org/category/core/)
## How to Report Bugs
### Make sure it is a jQuery bug
Many bugs reported to our bug tracker are actually bugs in user code, not in jQuery code. Keep in mind that just because your code throws an error and the console points to a line number inside of jQuery, this does *not* mean the bug is a jQuery bug; more often than not, these errors result from providing incorrect arguments when calling a jQuery function.
Most bugs reported to our bug tracker are actually bugs in user code, not in jQuery code. Keep in mind that just because your code throws an error inside of jQuery, this does *not* mean the bug is a jQuery bug.
If you are new to jQuery, it is usually a much better idea to ask for help first in the [Using jQuery Forum](http://forum.jquery.com/using-jquery) or the [jQuery IRC channel](http://webchat.freenode.net/?channels=%23jquery). You will get much quicker support, and you will help avoid tying up the jQuery team with invalid bug reports. These same resources can also be useful if you want to confirm that your bug is indeed a bug in jQuery before filing any tickets.
Ask for help first in the [Using jQuery Forum](http://forum.jquery.com/using-jquery) or another discussion forum like [Stack Overflow](http://stackoverflow.com/). You will get much quicker support, and you will help avoid tying up the jQuery team with invalid bug reports.
### Disable any browser extensions
### Disable browser extensions
Make sure you have reproduced the bug with all browser extensions and add-ons disabled, as these can sometimes cause things to break in interesting and unpredictable ways. Try using incognito, stealth or anonymous browsing modes.
### Try the latest version of jQuery
Bugs in old versions of jQuery may have already been fixed. In order to avoid reporting known issues, make sure you are always testing against the [latest build](http://code.jquery.com/jquery.js).
Bugs in old versions of jQuery may have already been fixed. In order to avoid reporting known issues, make sure you are always testing against the [latest build](http://code.jquery.com/jquery.js). We cannot fix bugs in older released files, if a bug has been fixed in a subsequent version of jQuery the site should upgrade.
### Try an older version of jQuery
### Simplify the test case
Sometimes, bugs are introduced in newer versions of jQuery that do not exist in previous versions. When possible, it can be useful to try testing with an older release.
When experiencing a problem, [reduce your code](http://webkit.org/quality/reduction.html) to the bare minimum required to reproduce the issue. This makes it *much* easier to isolate and fix the offending code. Bugs reported without reduced test cases take on average 9001% longer to fix than bugs that are submitted with them, so you really should try to do this if at all possible.
### Reduce, reduce, reduce!
### Search for related or duplicate issues
When you are experiencing a problem, the most useful thing you can possibly do is to [reduce your code](http://webkit.org/quality/reduction.html) to the bare minimum required to reproduce the issue. This makes it *much* easier to isolate and fix the offending code. Bugs that are reported without reduced test cases take on average 9001% longer to fix than bugs that are submitted with them, so you really should try to do this if at all possible.
Go to the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues) and make sure the problem hasn't already been reported. If not, create a new issue there and include your test case.
## jQuery Core Style Guide
See: [jQuery's Style Guides](http://contribute.jquery.org/style-guide/)
## Tips For Bug Patching
### Environment: localhost w/ PHP, Node & Grunt
Starting in jQuery 1.8, a newly overhauled development workflow has been introduced. In this new system, we rely on node & gruntjs to automate the building and validation of source code—while you write code.
The Ajax tests still depend on PHP running locally*, so make sure you have the following installed:
* Some kind of localhost server program that supports PHP (any will do)
* Node.js
* NPM (comes with the latest version of Node.js)
* Grunt (install with: `npm install grunt -g`
Maintaining a list of platform specific instructions is outside of the scope of this document and there is plenty of existing documentation for the above technologies.
* The PHP dependency will soon be shed in favor of an all-node solution.
We *love* when people contribute back to the project by patching the bugs they find. Since jQuery is used by so many people, we are cautious about the patches we accept and want to be sure they don't have a negative impact on the millions of people using jQuery each day. For that reason it can take a while for any suggested patch to work its way through the review and release process. The reward for you is knowing that the problem you fixed will improve things for millions of sites and billions of visits per day.
### Build a Local Copy of jQuery
@ -126,74 +106,6 @@ Now open the jQuery test suite in a browser at http://localhost/test. If there i
Success! You just built and tested jQuery!
### Fix a bug from a ticket filed on Github:
**NEVER write your patches to the master branch** - it gets messy (I say this from experience!)
**ALWAYS USE A "TOPIC" BRANCH!** Like so (#### = the ticket #)...
Make sure you start with your up-to-date master:
```bash
$ git checkout master
```
Create and checkout a new branch that includes the ticket #
```bash
$ git checkout -b bug_####
# ( Explanation: this useful command will:
# "checkout" a "-b" (branch) by the name of "bug_####"
# or create it if it doesn't exist )
```
Now you're on branch: bug_####
Determine the module/file you'll be working in...
Open up the corresponding /test/unit/?????.js and add the initial failing unit tests. This may seem awkward at first, but in the long run it will make sense. To truly and efficiently patch a bug, you need to be working against that bug.
Next, open the module files and make your changes
Run http://localhost/test --> **ALL TESTS MUST PASS**
Once you're satisfied with your patch...
Stage the files to be tracked:
```bash
$ git add filename
# (you can use "git status" to list the files you've changed)
```
( I recommend NEVER, EVER using "git add . " )
Once you've staged all of your changed files, go ahead and commit them
```bash
$ git commit -m "Brief description of fix. Fixes #0000"
```
For a multiple line commit message, leave off the `-m "description"`.
You will then be led into vi (or the text editor that you have set up) to complete your commit message.
Then, push your branch with the bug fix commits to your github fork
```bash
$ git push origin -u bug_####
```
Before you tackle your next bug patch, return to the master:
```bash
$ git checkout master
```
### Test Suite Tips...
During the process of writing your patch, you will run the test suite MANY times. You can speed up the process by narrowing the running test suite down to the module you are testing by either double clicking the title of the test or appending it to the url. The following examples assume you're working on a local repo, hosted on your localhost server.