Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 89 lines (50 sloc) 4.804 kb
2c4e95a @ariya Use GitHub contributing guide feature.
authored
1 # Contribution Guide
2
3 This page describes how to contribute changes to PhantomJS.
4
5 Please do **not** create a pull request without reading this guide first. Failure to do so may result in the **rejection** of the pull request.
6
7 ## For The Impatients
8
9 **Work on a feature branch**.
10 If your changes need to be modified due to some reviews, it is less clutter to tweak an isolated feature branch and push it again.
11
12 **Create a ticket in the issue tracker**.
13 This serves as a placeholder for important feedback, review, or any future updates. Using GitHub commenting system is not optimal because it is *not searchable* and therefore impossible to locate again.
14
15 In the commit message:
16
17 * **Keep the first line < 72 characters**. Write additional paragraphs
18 if necessary.
19 * **Put the link to the issue** (see above). This is important for cross-referencing purposes.
20
21 ## Communicate
22
23 *Second opinion is always important.*
24
0d63e9c @ariya Contribution guide: highlight various aspects of communication.
authored
25 **Bug fixing**. If you have a fix for a bug, please attach your patch in the corresponding issue in the [issue tracker](http://issues.phantomjs.org/). If there is no entry for the bug yet, then please create a new one. If you are convenient working with Git, see the Get Ready section below on how to submit your change.
2c4e95a @ariya Use GitHub contributing guide feature.
authored
26
0d63e9c @ariya Contribution guide: highlight various aspects of communication.
authored
27 **Improvement and feature request**. If you have an improvement idea, please send an email to the [mailing list](http://groups.google.com/group/phantomjs) (preferable than contacting the developers directly) so that other people can give their insights and opinions. This is also important to avoid duplicate work.
2c4e95a @ariya Use GitHub contributing guide feature.
authored
28
0d63e9c @ariya Contribution guide: highlight various aspects of communication.
authored
29 **Task management**. Once the feature idea is agreed upon and translated into concrete actions and tasks, please use the [issue tracker](http://issues.phantomjs.org/) to create an issue for each individual task. Further technical discussion about the task and the implementation details should be carried out in the issue tracker.
2c4e95a @ariya Use GitHub contributing guide feature.
authored
30
0d63e9c @ariya Contribution guide: highlight various aspects of communication.
authored
31 **Extending with new API**. Whenever you want to introduce a new API, please send an email to the mailing list along with the link to the issue. Consider good API name for the object or function, read the [API Design Principle](http://developer.qt.nokia.com/wiki/API_Design_Principles) article. It may require few iterations to agree on the final API and hence it is important to engage all interested parties as early as possible.
2c4e95a @ariya Use GitHub contributing guide feature.
authored
32
33 ## Get Ready
34
35 For your proposed change, you need to have:
36
37 * **an issue** (in the issue tracker) which describe your bug or feature
38 * **a feature branch** in your git fork
39
40 ### Refer the Issue
41
42 The commit message needs to link to the issue. This cross-reference is [very important](http://ariya.ofilabs.com/2012/01/small-scale-software-craftsmanship.html) for the following reasons.
43
44 First, the commit log is frozen and can not be changed. If it contains a mistake or outdated information, the log can not be amended. However, further updates can be still posted to the linked issue, which can be followed from the commit log itself.
45
46 Second, it provides a placeholder for code review and other feedback. Reviewing the change using GitHub commenting system is not encouraged because it is [not searchable](http://ariya.ofilabs.com/2012/08/github-and-lack-of-searchability.html) at all (if there is a future need to refer the previous discussion again, the comment is almost impossible to locate)
47
48 An example of a bad commit log:
49
50 Fix Mountain Lion
51
52 The above log is too short and useless in the long run. A better version (and note the issue link):
53
54 Better support for OS X Mountain Lion.
55
56 require('system').os.version should give "10.8 (Mountain Lion)".
57
58 http://code.google.com/p/phantomjs/issues/detail?id=688
59
60 ### Use Feature Branch
61
62 To isolate your change, please avoid working on the master branch. Instead, work on a *feature branch* (often also known as *topic branch*). You can create a new branch (example here crash-fix) off the master branch by using:
63
64 git checkout -b crash-fix master
65
66 Refer to your favorite Git tutorial/book for further detailed help.
67
68 Some good practices for the feature branch:
69
70 * Give it a meaningful name instead of, e.g. `prevent-zero-divide` instead of just `fix`
71 * Make *granular* and *atomic* commits, e.g. do not mix a typo fix with some major refactoring
72 * Keep one branch for one specific issue. If you need to work on other unrelated issues, create another branch.
73
74 ## Review and Merge
75
76 When your branch is ready, send the pull request.
77
78 While it is not always the case, often it is necessary to improve parts of your code in the branch. This is the actual review process.
79
80 Here is a check list for the review:
81
82 * It does not break the test suite
83 * There is no typo
84 * The coding style follows the existing one
85 * There is a reasonable amount of comment
86 * The license header is intact
87 * All examples are still working
88
Something went wrong with that request. Please try again.