fixed #241 - added CONTRIBUTING.md
Showing
2 changed files
with
98 additions
and
1 deletions
CONTRIBUTING.md
0 → 100644
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 | ... | ... |
-
Please register or sign in to post a comment