|
| 1 | +# Contributing to Angular 2 |
| 2 | + |
| 3 | +We would love for you to contribute to Angular 2 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 | + - [Submission Guidelines](#submit) |
| 11 | + - [Coding Rules](#rules) |
| 12 | + - [Commit Message Guidelines](#commit) |
| 13 | + - [Signing the CLA](#cla) |
| 14 | + |
| 15 | +## <a name="coc"></a> Code of Conduct |
| 16 | +Help us keep Angular open and inclusive. Please read and follow our [Code of Conduct][coc]. |
| 17 | + |
| 18 | +## <a name="question"></a> Got a Question or Problem? |
| 19 | + |
| 20 | +If you have questions about how to *use* Angular, please direct them to the [Google Group][angular-group] |
| 21 | +discussion list or [StackOverflow][stackoverflow]. We are also available on [Gitter][gitter]. |
| 22 | + |
| 23 | +## <a name="issue"></a> Found an Issue? |
| 24 | +If you find a bug in the source code or a mistake in the documentation, you can help us by |
| 25 | +[submitting an issue](#submit-issue) to our [GitHub Repository][github]. Even better, you can |
| 26 | +[submit a Pull Request](#submit-pr) with a fix. |
| 27 | + |
| 28 | +## <a name="feature"></a> Want a Feature? |
| 29 | +You can *request* a new feature by [submitting an issue](#submit-issue) to our [GitHub |
| 30 | +Repository][github]. If you would like to *implement* a new feature then consider what kind of |
| 31 | +change it is: |
| 32 | + |
| 33 | +* For a **Major Feature**, first open an issue and outline your proposal so that it can be |
| 34 | +discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, |
| 35 | +and help you to craft the change so that it is successfully accepted into the project. |
| 36 | +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). |
| 37 | + |
| 38 | +## <a name="docs"></a> Want a Doc Fix? |
| 39 | +If you want to help improve the docs, then consider what kind of improvement it is: |
| 40 | + |
| 41 | +* For **Major Changes**, it's a good idea to let others know what you're working on to |
| 42 | +minimize duplication of effort. Before starting, check out the issue queue for |
| 43 | +issues labeled [#docs](https://github.com/angular/angular/labels/%23docs). |
| 44 | +Comment on an issue to let others know what you're working on, or [create a new issue](#submit-issue) |
| 45 | +if your work doesn't fit within the scope of any of the existing doc issues. |
| 46 | +Please build and test the documentation before [submitting the Pull Request](#submit-pr), to be sure |
| 47 | +you haven't accidentally introduced any layout or formatting issues. Also ensure that your commit |
| 48 | +message is labeled "docs" and follows the [Commit Message Guidelines](#commit) given below. |
| 49 | +* For **Small Changes**, there is no need to file an issue first. Simply [submit a Pull Request](#submit-pr). |
| 50 | + |
| 51 | +## <a name="submit"></a> Submission Guidelines |
| 52 | + |
| 53 | +### <a name="submit-issue"></a> Submitting an Issue |
| 54 | +Before you submit an issue, search the archive, maybe your question was already answered. |
| 55 | + |
| 56 | +If your issue appears to be a bug, and hasn't been reported, open a new issue. |
| 57 | +Help us to maximize the effort we can spend fixing issues and adding new |
| 58 | +features, by not reporting duplicate issues. Providing the following information will increase the |
| 59 | +chances of your issue being dealt with quickly: |
| 60 | + |
| 61 | +* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps |
| 62 | +* **Motivation for or Use Case** - explain why this is a bug for you |
| 63 | +* **Angular Version(s)** - is it a regression? |
| 64 | +* **Browsers and Operating System** - is this a problem with all browsers? |
| 65 | +* **Reproduce the Error** - provide a live example (using [Plunker][plunker], |
| 66 | + [JSFiddle][jsfiddle] or [Runnable][runnable]) or a unambiguous set of steps. |
| 67 | +* **Related Issues** - has a similar issue been reported before? |
| 68 | +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be |
| 69 | + causing the problem (line of code or commit) |
| 70 | + |
| 71 | +### <a name="submit-pr"></a> Submitting a Pull Request (PR) |
| 72 | +Before you submit your Pull Request (PR) consider the following guidelines: |
| 73 | + |
| 74 | +* Search [GitHub](https://github.com/angular/angular.dart/pulls) for an open or closed PR |
| 75 | + that relates to your submission. You don't want to duplicate effort. |
| 76 | +* Please sign our [Contributor License Agreement (CLA)](#cla) before sending PRs. |
| 77 | + We cannot accept code without this. |
| 78 | +* Make your changes in a new git branch: |
| 79 | + |
| 80 | + ```shell |
| 81 | + git checkout -b my-fix-branch master |
| 82 | + ``` |
| 83 | + |
| 84 | +* Create your patch, **including appropriate test cases**. |
| 85 | +* Follow our [Coding Rules](#rules). |
| 86 | +* Run the full Angular test suite, as described in the [developer documentation][dev-doc], |
| 87 | + and ensure that all tests pass. |
| 88 | +* Commit your changes using a descriptive commit message that follows our |
| 89 | + [commit message conventions](#commit). Adherence to these conventions |
| 90 | + is necessary because release notes are automatically generated from these messages. |
| 91 | + |
| 92 | + ```shell |
| 93 | + git commit -a |
| 94 | + ``` |
| 95 | + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. |
| 96 | + |
| 97 | +* Push your branch to GitHub: |
| 98 | + |
| 99 | + ```shell |
| 100 | + git push origin my-fix-branch |
| 101 | + ``` |
| 102 | + |
| 103 | +* In GitHub, send a pull request to `angular:master`. |
| 104 | +* If we suggest changes then: |
| 105 | + * Make the required updates. |
| 106 | + * Re-run the Angular 2 test suites for JS and Dart to ensure tests are still passing. |
| 107 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 108 | + |
| 109 | + ```shell |
| 110 | + git rebase master -i |
| 111 | + git push -f |
| 112 | + ``` |
| 113 | + |
| 114 | +That's it! Thank you for your contribution! |
| 115 | +
|
| 116 | +#### After your pull request is merged |
| 117 | +
|
| 118 | +After your pull request is merged, you can safely delete your branch and pull the changes |
| 119 | +from the main (upstream) repository: |
| 120 | +
|
| 121 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 122 | +
|
| 123 | + ```shell |
| 124 | + git push origin --delete my-fix-branch |
| 125 | + ``` |
| 126 | +
|
| 127 | +* Check out the master branch: |
| 128 | +
|
| 129 | + ```shell |
| 130 | + git checkout master -f |
| 131 | + ``` |
| 132 | +
|
| 133 | +* Delete the local branch: |
| 134 | +
|
| 135 | + ```shell |
| 136 | + git branch -D my-fix-branch |
| 137 | + ``` |
| 138 | +
|
| 139 | +* Update your master with the latest upstream version: |
| 140 | +
|
| 141 | + ```shell |
| 142 | + git pull --ff upstream master |
| 143 | + ``` |
| 144 | +
|
| 145 | +## <a name="rules"></a> Coding Rules |
| 146 | +To ensure consistency throughout the source code, keep these rules in mind as you are working: |
| 147 | +
|
| 148 | +* All features or bug fixes **must be tested** by one or more specs (unit-tests). |
| 149 | +* All public API methods **must be documented**. (Details TBC). |
| 150 | +* With the exceptions listed below, we follow the rules contained in |
| 151 | + [Google's JavaScript Style Guide][js-style-guide]: |
| 152 | + * Wrap all code at **100 characters**. |
| 153 | + |
| 154 | +## <a name="commit"></a> Commit Message Guidelines |
| 155 | + |
| 156 | +We have very precise rules over how our git commit messages can be formatted. This leads to **more |
| 157 | +readable messages** that are easy to follow when looking through the **project history**. But also, |
| 158 | +we use the git commit messages to **generate the Angular change log**. |
| 159 | + |
| 160 | +### Commit Message Format |
| 161 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special |
| 162 | +format that includes a **type**, a **scope** and a **subject**: |
| 163 | + |
| 164 | +``` |
| 165 | +<type>(<scope>): <subject> |
| 166 | +<BLANK LINE> |
| 167 | +<body> |
| 168 | +<BLANK LINE> |
| 169 | +<footer> |
| 170 | +``` |
| 171 | + |
| 172 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 173 | +to read on GitHub as well as in various git tools. |
| 174 | + |
| 175 | +### Type |
| 176 | +Must be one of the following: |
| 177 | + |
| 178 | +* **feat**: A new feature |
| 179 | +* **fix**: A bug fix |
| 180 | +* **docs**: Documentation only changes |
| 181 | +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing |
| 182 | + semi-colons, etc) |
| 183 | +* **refactor**: A code change that neither fixes a bug or adds a feature |
| 184 | +* **perf**: A code change that improves performance |
| 185 | +* **test**: Adding missing tests |
| 186 | +* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation |
| 187 | + generation |
| 188 | + |
| 189 | +### Scope |
| 190 | +The scope could be anything specifying place of the commit change. For example |
| 191 | +`Compiler`, `ElementInjector`, etc. |
| 192 | + |
| 193 | +### Subject |
| 194 | +The subject contains succinct description of the change: |
| 195 | + |
| 196 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 197 | +* don't capitalize first letter |
| 198 | +* no dot (.) at the end |
| 199 | +
|
| 200 | +### Body |
| 201 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 202 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 203 | +
|
| 204 | +### Footer |
| 205 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 206 | +reference GitHub issues that this commit **Closes**. |
| 207 | +
|
| 208 | +
|
| 209 | +A detailed explanation can be found in this [document][commit-message-format]. |
| 210 | +
|
| 211 | +## <a name="cla"></a> Signing the CLA |
| 212 | +
|
| 213 | +Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code |
| 214 | +changes to be accepted, the CLA must be signed. It's a quick process, we promise! |
| 215 | + |
| 216 | +* For individuals we have a [simple click-through form][individual-cla]. |
| 217 | +* For corporations we'll need you to |
| 218 | + [print, sign and one of scan+email, fax or mail the form][corporate-cla]. |
| 219 | +
|
| 220 | +
|
| 221 | +[angular-group]: https://groups.google.com/forum/#!forum/angular |
| 222 | +[coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md |
| 223 | +[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit# |
| 224 | +[corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html |
| 225 | +[dev-doc]: https://github.com/angular/angular/blob/master/DEVELOPER.md |
| 226 | +[github]: https://github.com/angular/angular |
| 227 | +[gitter]: https://gitter.im/angular/angular |
| 228 | +[individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html |
| 229 | +[js-style-guide]: http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml |
| 230 | +[jsfiddle]: http://jsfiddle.net/ |
| 231 | +[plunker]: http://plnkr.co/edit |
| 232 | +[runnable]: http://runnable.com/ |
| 233 | +[stackoverflow]: http://stackoverflow.com/questions/tagged/angular |
0 commit comments