|
| 1 | +# Contributing to AngularFire2 |
| 2 | + |
| 3 | +We would love for you to contribute to AngularFire2 and help make it even better than it is |
| 4 | +today! As a contributor, here are the guidelines we would like you to follow: |
| 5 | + |
| 6 | + - [Code of Conduct](#coc) |
| 7 | + - [Question or Problem?](#question) |
| 8 | + - [Issues and Bugs](#issue) |
| 9 | + - [Feature Requests](#feature) |
| 10 | + - [Initial Setup](#setup) |
| 11 | + - [Submission Guidelines](#submit) |
| 12 | + - [Submitting an Issue](#submit-issue) |
| 13 | + - [Submitting a Pull Request](#submit-pr) |
| 14 | + - [Before you submit](#submit-before) |
| 15 | + - [How to submit](#submit-how) |
| 16 | + - [Deploying docs](#submit-docs) |
| 17 | + - Appendix |
| 18 | + - [Coding Rules][rules] (external link) |
| 19 | + - [Commit Message Guidelines][commit] (external link) |
| 20 | + - [Signing the CLA](#cla) |
| 21 | + |
| 22 | +## <a name="coc"></a> Code of Conduct |
| 23 | + |
| 24 | +Help us keep the Angular and Firebase communities open and inclusive. Please read and follow the Angular [Code of Conduct][coc]. |
| 25 | + |
| 26 | +## <a name="question"></a> Got a Question or Problem? |
| 27 | + |
| 28 | +If you have questions about how to *use* AngularFire, please direct them to the [Angular Google Group][angular-group] |
| 29 | +discussion list or [StackOverflow][stackoverflow] (include the `firebase` and `angular` tags!). |
| 30 | +Please note that the Angular team's capacity to answer usage questions is limited. |
| 31 | +Members of the Firebase team can be reached on [Slack][slack] and via the [Firebase Google Group][firebase-group]. |
| 32 | + |
| 33 | +## <a name="issue"></a> Found an Issue? |
| 34 | + |
| 35 | +If you find a bug in the source code, you can help us by |
| 36 | +[submitting an issue](#submit-issue) to our [GitHub Repository][github]. Even better, you can |
| 37 | +[submit a Pull Request](#submit-pr) with a fix. |
| 38 | + |
| 39 | +## <a name="feature"></a> Want a Feature? |
| 40 | + |
| 41 | +You can *request* a new feature by [submitting an issue](#submit-issue) to our [GitHub |
| 42 | +Repository][github]. If you would like to *implement* a new feature, please submit an issue with |
| 43 | +a proposal for your work first, to be sure that we can use it. |
| 44 | +Please consider what kind of change it is: |
| 45 | + |
| 46 | +* For a **Major Feature**, first open an issue and outline your proposal so that it can be |
| 47 | +discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, |
| 48 | +and help you to craft the change so that it is successfully accepted into the project. |
| 49 | +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). |
| 50 | + |
| 51 | +## <a name="setup"></a> Initial Setup |
| 52 | + |
| 53 | +1) Create a fork of AngularFire2 (See [Forking a Project][github-fork]) |
| 54 | + |
| 55 | +2) CD into your clone and install dependencies |
| 56 | + |
| 57 | +```shell |
| 58 | +$ git clone |
| 59 | +$ npm install |
| 60 | +$ npm run build |
| 61 | +$ npm test |
| 62 | +``` |
| 63 | + |
| 64 | +3) Make your changes in a new git branch: |
| 65 | + |
| 66 | +```shell |
| 67 | +git checkout -b my-fix-branch master |
| 68 | +``` |
| 69 | + |
| 70 | +## <a name="submit"></a> Submission Guidelines |
| 71 | + |
| 72 | +### <a name="submit-issue"></a> Submitting an Issue |
| 73 | +Help us to maximize the effort we can spend improving the product by not reporting duplicate issues. |
| 74 | +Search the archives before you submit. |
| 75 | + |
| 76 | +Providing the following information will increase the chances of your issue being dealt with quickly: |
| 77 | + |
| 78 | +* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps |
| 79 | +* **Angular Version** - what version of Angular, Firebase, and AngularFire are you using? |
| 80 | +* **Motivation for or Use Case** - explain what are you trying to do and why the current behavior is a bug for you |
| 81 | +* **Browsers and Operating System** - is this a problem with all browsers? |
| 82 | +* **Reproduce the Error** - provide a live example (using [Plunker][plunker], |
| 83 | + [JSFiddle][jsfiddle] or [Runnable][runnable]) or a unambiguous set of steps |
| 84 | +* **Related Issues** - has a similar issue been reported before? |
| 85 | +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be |
| 86 | + causing the problem (line of code or commit) |
| 87 | + |
| 88 | +You can file new issues by providing the above information [here](https://github.com/angular/angularfire2/issues/new). |
| 89 | + |
| 90 | +### <a name="submit-pr"></a> Submitting a Pull Request (PR) |
| 91 | + |
| 92 | +#### <a name="submit-before"></a> Before you submit: |
| 93 | + |
| 94 | +* Ensure proposed changes or problem have already been clearly defined and |
| 95 | + discussed in the issue tracker. We don't want you to burn time on code |
| 96 | + that isn't a good fit for the project. |
| 97 | +* Search [GitHub](https://github.com/angular/angularfire2/pulls) for an open or closed PR |
| 98 | + that relates to your submission. You don't want to duplicate effort. |
| 99 | +* Please sign our [Contributor License Agreement (CLA)](#cla) before sending PRs. |
| 100 | + We cannot accept code without this. |
| 101 | +* Review our [Coding Rules][rules] (external link) |
| 102 | +* Review our [Commit Message Guidelines][commit] (external link) |
| 103 | + |
| 104 | +#### <a name="submit-how"></a> How to submit: |
| 105 | + |
| 106 | +* Create your patch, **including appropriate test cases**. |
| 107 | +* Follow the [Angular Coding Rules][rules]. |
| 108 | +* Run the full test suite, as described in the [developer documentation][dev-doc], |
| 109 | + and ensure that all tests pass. |
| 110 | +* Commit your changes using a descriptive commit message that follows the |
| 111 | + [Angular commit message conventions][commit]. Adherence to these conventions |
| 112 | + is necessary because release notes are automatically generated from these messages. |
| 113 | + |
| 114 | + ```shell |
| 115 | + git commit -a |
| 116 | + ``` |
| 117 | + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. |
| 118 | + |
| 119 | +* Push your branch to GitHub: |
| 120 | + |
| 121 | + ```shell |
| 122 | + git push origin my-fix-branch |
| 123 | + ``` |
| 124 | + |
| 125 | +* In GitHub, send a pull request to `angular:master`. |
| 126 | +* If we suggest changes then: |
| 127 | + * Make the required updates. |
| 128 | + * Re-run the test suites to ensure tests are still passing. |
| 129 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 130 | + |
| 131 | + ```shell |
| 132 | + git rebase master -i |
| 133 | + git push -f |
| 134 | + ``` |
| 135 | + |
| 136 | +That's it! Thank you for your contribution! |
| 137 | +
|
| 138 | +#### <a name="submit-docs"></a> Deploying Docs |
| 139 | +
|
| 140 | +1) Build the docs |
| 141 | +
|
| 142 | +`$ npm run docs` |
| 143 | +
|
| 144 | +2) Deploy Docs to Firebase Hosting |
| 145 | +
|
| 146 | +(Ask @jeffbcross to add you as a collaborator or deploy on your behalf) |
| 147 | +
|
| 148 | +``` |
| 149 | +$ npm install -g firebase-tools |
| 150 | +$ firebase login |
| 151 | +$ npm run docs |
| 152 | +$ cd docs |
| 153 | +$ firebase deploy |
| 154 | +``` |
| 155 | +
|
| 156 | +## <a name="cla"></a> Signing the CLA |
| 157 | +
|
| 158 | +Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code |
| 159 | +changes to be accepted, the CLA must be signed. It's a quick process, we promise! |
| 160 | + |
| 161 | +* For individuals we have a [simple click-through form][individual-cla]. |
| 162 | +* For corporations we'll need you to |
| 163 | + [print, sign and one of scan+email, fax or mail the form][corporate-cla]. |
| 164 | +
|
| 165 | +
|
| 166 | +[slack]: https://firebase-community.appspot.com/ |
| 167 | +[coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md |
| 168 | +[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit# |
| 169 | +[corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html |
| 170 | +[individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html |
| 171 | +[js-style-guide]: https://google.github.io/styleguide/javascriptguide.xml |
| 172 | +[jsfiddle]: http://jsfiddle.net |
| 173 | +[plunker]: http://plnkr.co/edit |
| 174 | +[runnable]: http://runnable.com |
| 175 | +[github]: https://github.com/angular/angularfire2 |
| 176 | +[stackoverflow]: http://stackoverflow.com/questions/tagged/angularfire |
| 177 | +[rules]: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#rules |
| 178 | +[commit]: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines |
| 179 | +[angular-group]: https://groups.google.com/forum/#!forum/angular |
| 180 | +[firebase-group]: https://groups.google.com/forum/#!forum/firebase-talk |
| 181 | +[github-fork]: https://help.github.com/articles/fork-a-repo/ |
0 commit comments