Commit 62e94ac4 62e94ac4cda5099db209b72a0248145db3c240fa by Nicolas Perriault

fixed #241 - added CONTRIBUTING.md

1 parent 6e13cca2
1 # Contribution Guide
2
3 *Note: this guide has been heavily inspired by [PhantomJS' one](https://github.com/ariya/phantomjs/blob/master/CONTRIBUTING.md)*
4
5 **This page describes how to contribute changes to the [CasperJS](http://casperjs.org/) project.**
6
7 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.
8
9 ## For The Impatients
10
11 **Work on a feature branch**.
12 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.
13
14 **Create a ticket in the [issue tracker](https://github.com/n1k0/casperjs/issues/)**.
15 This serves as a placeholder for important feedback, review, or any future updates. **Please ensure searchning the bugtracker for an already opened issue matching your case.**
16
17 In the commit message:
18
19 * **Keep the first line short**. Write additional paragraphs if necessary.
20 * **Reference an opened issue**, by referencing the issue ID prefixed by a `#` and the keyword `refs`, eg. `refs #123`
21
22 Sample commit message:
23
24 > refs #123 - fixed error message formatting
25 >
26 > (optional: a short explanation of what the patch actually does)
27
28 **Run tests**
29
30 Run CasperJS' test suite to see you didn't break something:
31
32 $ casperjs selftest
33
34 The result status bar **must be green** before sending your PR.
35
36 ## Communicate
37
38 **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.
39
40 **Help request**. If you're stuck using CasperJS and don't understand how to achieve something, please [ask on the mailing-list](https://groups.google.com/forum/#!forum/casperjs) first. Please don't ask for all the kind people to write your scripts for you.
41
42 **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 if any. 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.
43
44 ## Get Ready
45
46 ### Use Feature Branch
47
48 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:
49
50 git checkout -b crash-fix master
51
52 Refer to your favorite Git tutorial/book for further detailed help.
53
54 Some good practices for the feature branch:
55
56 * Give it a meaningful name instead of, e.g. `prevent-zero-divide` instead of just `fix`
57 * Make *granular* and *atomic* commits, e.g. do not mix a typo fix with some major refactoring
58 * Keep one branch for one specific issue. If you need to work on other unrelated issues, create another branch.
59
60 ### Write tests
61
62 CasperJS being partly a testing framework, how irrelevant would be to send a pull request with no test? So, please take the time to write and attach tests to your PR. Furthermore, testing with CasperJS is quite [exhaustively documented](http://casperjs.org/testing.html).
63
64 ### Run tests!
65
66 This may sound obvious but **don't send pull requests which break the casperjs test suite**.
67
68 To see if your modifications broke the suite, just run:
69
70 $ casperjs selftest
71
72 ### Write documentation
73
74 Do you appreciate the [CasperJS documentation](http://casperjs.org/)? I do too. As the documentation contents are managed and generated using Github, Markdown and CasperJS itself, take the time to read the [Documentation Contribution Guide](https://github.com/n1k0/casperjs/blob/gh-pages/README.md#casperjs-documentation) and write the documentation related to your PR whenever applicable.
75
76 **Note:** As the documentation is handled in a [dedicated separated `gh-pages` branch](https://github.com/n1k0/casperjs/tree/gh-pages), you'll have to send a dedicated PR for doc patches. I'm working on a more comfortable solution, but it's no easy task though.
77
78 ## Review and Merge
79
80 When your branch is ready, send the pull request.
81
82 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.
83
84 Here is a check list for the review:
85
86 * It does not break the test suite
87 * There is no typo
88 * The coding style follows the existing one
89 * There is a reasonable amount of comment
90 * The license header is intact
91 * All examples are still working
...@@ -23,7 +23,13 @@ Subscribe to the [project mailing-list](https://groups.google.com/forum/#!forum/ ...@@ -23,7 +23,13 @@ Subscribe to the [project mailing-list](https://groups.google.com/forum/#!forum/
23 23
24 Follow the CasperJS project [on twitter](https://twitter.com/casperjs_org) and [Google+](https://plus.google.com/b/106641872690063476159/). 24 Follow the CasperJS project [on twitter](https://twitter.com/casperjs_org) and [Google+](https://plus.google.com/b/106641872690063476159/).
25 25
26 ## Contributing to the docs 26 ## Contributing
27
28 ### Contributing code
29
30 Please read the [CONTRIBUTING.md](https://github.com/n1k0/casperjs/blob/master/CONTRIBUTING.md) file contents.
31
32 ### Contributing documentation
27 33
28 CasperJS's documentation is written using the [Markdown format](http://daringfireball.net/projects/markdown/), and hosted on Github thanks to the [Github Pages Feature](http://pages.github.com/). 34 CasperJS's documentation is written using the [Markdown format](http://daringfireball.net/projects/markdown/), and hosted on Github thanks to the [Github Pages Feature](http://pages.github.com/).
29 35
......