| OLD | NEW |
| 1 # Contributing to AngularDart | 1 # Contributing to AngularDart |
| 2 | 2 |
| 3 We have set up a [milestone][communityMilestone] for issues which we believe are
an excellent | 3 We have set up a [milestone][communityMilestone] for issues that we believe are
an excellent |
| 4 place to start if you are interested in contributing to AngularDart. | 4 place to start if you are interested in contributing to AngularDart. |
| 5 | 5 |
| 6 We'd love for you to contribute to our source code and to make AngularDart even
better than it is | 6 We'd love for you to contribute to our source code and to make AngularDart even
better than it is |
| 7 today! Here are the guidelines we'd like you to follow: | 7 today! Here are the guidelines we'd like you to follow: |
| 8 | 8 |
| 9 ## Code of Conduct | 9 - [Code of Conduct](#coc) |
| 10 - [Question or Problem?](#question) |
| 11 - [Issues and Bugs](#issue) |
| 12 - [Feature Requests](#feature) |
| 13 - [Submission Guidelines](#submit) |
| 14 - [Coding Rules](#rules) |
| 15 - [Commit Message Guidelines](#commit) |
| 16 - [Signing the CLA](#cla) |
| 17 |
| 18 ## <a name="coc"></a> Code of Conduct |
| 10 Help us keep Angular open and inclusive. Please read and follow our [Code of Con
duct][coc]. | 19 Help us keep Angular open and inclusive. Please read and follow our [Code of Con
duct][coc]. |
| 11 | 20 |
| 12 ## Got a Question or Problem? | 21 ## <a name="question"></a> Got a Question or Problem? |
| 13 | 22 |
| 14 If you have questions about how to use AngularDart, please direct these to the [
Google Group][groups] | 23 If you have questions about how to use AngularDart, please direct these to the [
Google Group][groups] |
| 15 discussion list or [StackOverflow][stackoverflow]. | 24 discussion list or [StackOverflow][stackoverflow]. |
| 16 | 25 |
| 17 ## Found an Issue? | 26 ## <a name="issue"></a> Found an Issue? |
| 18 If you find a bug in the source code or a mistake in the documentation, you can
help us by | 27 If you find a bug in the source code or a mistake in the documentation, you can
help us by |
| 19 submitting and issue to our [GitHub Repository][github]. Even better you can sub
mit a Pull Request | 28 submitting and issue to our [GitHub Repository][github]. Even better you can sub
mit a Pull Request |
| 20 with a fix. | 29 with a fix. |
| 21 | 30 |
| 22 **Please see the Submission Guidelines below**. | 31 **Please see the Submission Guidelines below**. |
| 23 | 32 |
| 24 ## Want a Feature? | 33 ## <a name="feature"></a> Want a Feature? |
| 25 You can request a new feature by submitting an issue to our [GitHub Repository][
github]. If you | 34 You can request a new feature by submitting an issue to our [GitHub Repository][
github]. If you |
| 26 would like to implement a new feature then consider what kind of change it is: | 35 would like to implement a new feature then consider what kind of change it is: |
| 27 | 36 |
| 28 <!-- | 37 <!-- |
| 29 * **Major Changes** that you wish to contribute to the project should be discuss
ed first on our | 38 * **Major Changes** that you wish to contribute to the project should be discuss
ed first on our |
| 30 [dev mailing list][angular-dev] or [IRC][irc] so that we can better coordinate o
ur efforts, prevent | 39 [dev mailing list][angular-dev] or [IRC][irc] so that we can better coordinate o
ur efforts, prevent |
| 31 duplication of work, and help you to craft the change so that it is successfully
accepted into the | 40 duplication of work, and help you to craft the change so that it is successfully
accepted into the |
| 32 project. | 41 project. |
| 33 --> | 42 --> |
| 34 * **Small Changes** can be crafted and submitted to [GitHub Repository][github]
as a Pull Request. | 43 * **Small Changes** can be crafted and submitted to [GitHub Repository][github]
as a Pull Request. |
| 35 | 44 |
| 36 | 45 |
| 37 ## Want a Doc Fix? | 46 ## <a name="docs"></a> Want a Doc Fix? |
| 38 If you want to help improve the docs, it's a good idea to let others know what y
ou're working on to | 47 If you want to help improve the docs, it's a good idea to let others know what y
ou're working on to |
| 39 minimize duplication of effort. Before starting, check out the issue queue. | 48 minimize duplication of effort. Before starting, check out the issue queue. |
| 40 | 49 |
| 41 Comment on an issue to let others know what you're working on, or create a new i
ssue if your work | 50 Comment on an issue to let others know what you're working on, or create a new i
ssue if your work |
| 42 doesn't fit within the scope of any of the existing doc fix projects. | 51 doesn't fit within the scope of any of the existing doc fix projects. |
| 43 | 52 |
| 44 For large fixes, please build and test the documentation before submitting the P
R to be sure you haven't | 53 For large fixes, please build and test the documentation before submitting the P
R to be sure you haven't |
| 45 accidentally introduced any layout or formatting issues.You should also make sur
e that your commit message | 54 accidentally introduced any layout or formatting issues. You should also make su
re that your commit message |
| 46 is labeled "docs:" and follows the **Git Commit Guidelines** outlined below. | 55 is labeled "docs:" and follows the **Git Commit Guidelines** outlined below. |
| 47 | 56 |
| 48 ## Submission Guidelines | 57 ## <a name="submit"></a> Submission Guidelines |
| 49 | 58 |
| 50 ### Submitting an Issue | 59 ### Submitting an Issue |
| 51 Before you submit your issue search the archive, maybe your question was already
answered. | 60 Before you submit your issue search the archive, maybe your question was already
answered. |
| 52 | 61 |
| 53 If your issue appears to be a bug, and hasn't been reported, open a new issue. | 62 If your issue appears to be a bug, and hasn't been reported, open a new issue. |
| 54 Help us to maximize the effort we can spend fixing issues and adding new | 63 Help us to maximize the effort we can spend fixing issues and adding new |
| 55 features, by not reporting duplicate issues. Providing the following informatio
n will increase the | 64 features, by not reporting duplicate issues. Providing the following informatio
n will increase the |
| 56 chances of your issue being dealt with quickly: | 65 chances of your issue being dealt with quickly: |
| 57 | 66 |
| 58 * **Overview of the issue** - if an error is being thrown a non-minified stack t
race helps | 67 * **Overview of the issue** - if an error is being thrown a non-minified stack t
race helps |
| 59 * **Motivation for or Use Case** - explain why this is a bug for you | 68 * **Motivation for or Use Case** - explain why this is a bug for you |
| 60 * **Angular Version(s)** - is it a regression? | 69 * **Angular Version(s)** - is it a regression? |
| 61 * **Browsers and Operating System** - is this a problem with all browsers or onl
y IE8? | 70 * **Browsers and Operating System** - is this a problem with all browsers or onl
y IE8? |
| 62 * **Reproduce the error** - provide a live example (using [Runnable][runnable])
or a unambiguous set of steps. | 71 * **Reproduce the error** - provide a live example (using [Runnable][runnable])
or a unambiguous set of steps. |
| 63 * **Related issues** - has a similar issue been reported before? | 72 * **Related issues** - has a similar issue been reported before? |
| 64 * **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point t
o what might be | 73 * **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point t
o what might be |
| 65 causing the problem (line of code or commit) | 74 causing the problem (line of code or commit) |
| 66 | 75 |
| 67 **If you get help, help others. Good karma rulez!** | 76 **If you get help, help others. Good karma rulez!** |
| 68 | 77 |
| 69 ### Submitting a Pull Request | 78 ### Submitting a Pull Request |
| 70 Before you submit your pull request consider the following guidelines: | 79 Before you submit your pull request consider the following guidelines: |
| 71 | 80 |
| 72 * Search [GitHub][github] for an open or closed Pull Request | 81 * Search [GitHub](https://github.com/angular/angular.dart/pulls) for an open or
closed Pull Request |
| 73 that relates to your submission. You don't want to duplicate effort. | 82 that relates to your submission. You don't want to duplicate effort. |
| 74 * Please sign our [Contributor License Agreement (CLA)](#signing-the-cla) before
sending pull | 83 * Please sign our [Contributor License Agreement (CLA)](#signing-the-cla) before
sending pull |
| 75 requests. We cannot accept code without this. | 84 requests. We cannot accept code without this. |
| 76 * Make your changes in a new git branch | 85 * Make your changes in a new git branch |
| 77 | 86 |
| 78 ```shell | 87 ```shell |
| 79 git checkout -b my-fix-branch master | 88 git checkout -b my-fix-branch master |
| 80 ``` | 89 ``` |
| 81 | 90 |
| 82 * Create your patch, including appropriate test cases. | 91 * Create your patch, **including appropriate test cases**. |
| 83 * Follow our [Coding Rules](#coding-rules) | 92 * Follow our [Coding Rules](#coding-rules). |
| 84 * Commit your changes and create a descriptive commit message (the | 93 * Run the full Angular test suite, as described in the [developer documentation]
[dev-doc], |
| 85 commit message is used to generate release notes, please check out our | 94 and ensure that all tests pass. |
| 86 [commit message conventions](#commit-message-format) and our commit message pr
esubmit hook | 95 * Commit your changes using a descriptive commit message that follows our |
| 87 `validate-commit-msg.js`): | 96 [commit message conventions](#commit-message-format) and passes our commit mes
sage presubmit hook |
| 97 `validate-commit-msg.js`. Adherence to the [commit message conventions](#commi
t-message-format) |
| 98 is required because release notes are automatically generated from these messa
ges. |
| 88 | 99 |
| 89 ```shell | 100 ```shell |
| 90 git commit -a | 101 git commit -a |
| 91 ``` | 102 ``` |
| 103 Note: the optional commit `-a` command line option will automatically "add" an
d "rm" edited files. |
| 92 | 104 |
| 93 * Build your changes locally to ensure all the tests pass: see the [developer do
cumentation][dev-doc]. | 105 * Push your branch to GitHub: |
| 94 | |
| 95 * Push your branch to Github: | |
| 96 | 106 |
| 97 ```shell | 107 ```shell |
| 98 git push origin my-fix-branch | 108 git push origin my-fix-branch |
| 99 ``` | 109 ``` |
| 100 | 110 |
| 101 * In Github, send a pull request to `angular:master`. | 111 * In GitHub, send a pull request to `angular:master`. |
| 102 * If we suggest changes then you can modify your branch, rebase and force a new
push to your GitHub | 112 * If we suggest changes then |
| 103 repository to update the Pull Request: | 113 * Make the required updates. |
| 114 * Re-run the AngularDart test suite to ensure tests are still passing. |
| 115 * Rebase your branch and force push to your GitHub repository (this will updat
e your Pull Request): |
| 104 | 116 |
| 105 ```shell | 117 ```shell |
| 106 git rebase master -i | 118 git rebase master -i |
| 107 git push -f | 119 git push -f |
| 108 ``` | 120 ``` |
| 109 | 121 |
| 110 That's it! Thank you for your contribution! | 122 That's it! Thank you for your contribution! |
| 111 | 123 |
| 112 When the patch is reviewed and merged, you can safely delete your branch and pul
l the changes | 124 #### After your pull request is merged |
| 125 |
| 126 After your pull request is merged, you can safely delete your branch and pull th
e changes |
| 113 from the main (upstream) repository: | 127 from the main (upstream) repository: |
| 114 | 128 |
| 115 * Delete the remote branch on Github: | 129 * Delete the remote branch on GitHub either through the GitHub web UI or your lo
cal shell as follows: |
| 116 | 130 |
| 117 ```shell | 131 ```shell |
| 118 git push origin --delete my-fix-branch | 132 git push origin --delete my-fix-branch |
| 119 ``` | 133 ``` |
| 120 | 134 |
| 121 * Check out the master branch: | 135 * Check out the master branch: |
| 122 | 136 |
| 123 ```shell | 137 ```shell |
| 124 git checkout master -f | 138 git checkout master -f |
| 125 ``` | 139 ``` |
| 126 | 140 |
| 127 * Delete the local branch: | 141 * Delete the local branch: |
| 128 | 142 |
| 129 ```shell | 143 ```shell |
| 130 git branch -D my-fix-branch | 144 git branch -D my-fix-branch |
| 131 ``` | 145 ``` |
| 132 | 146 |
| 133 * Update your master with the latest upstream version: | 147 * Update your master with the latest upstream version: |
| 134 | 148 |
| 135 ```shell | 149 ```shell |
| 136 git pull --ff upstream master | 150 git pull --ff upstream master |
| 137 ``` | 151 ``` |
| 138 ## Coding Rules | 152 |
| 153 ## <a name="rules"></a> Coding Rules |
| 139 To ensure consistency throughout the source code, keep these rules in mind as yo
u are working: | 154 To ensure consistency throughout the source code, keep these rules in mind as yo
u are working: |
| 140 | 155 |
| 141 * All features or bug fixes **must be tested** by one or more [specs][unit-tes
ting]. | 156 * All features or bug fixes **must be tested** by one or more [specs][unit-tes
ting]. |
| 142 * All public API methods **must be documented** with [doc comments][doc-commen
ts]. | 157 * All public API methods **must be documented** with [doc comments][doc-commen
ts]. |
| 143 * With the exceptions listed below, we follow the rules contained in | 158 * With the exceptions listed below, we follow the rules contained in |
| 144 [Google's Dart Style Guide][dart-style-guide]. | 159 [Google's Dart Style Guide][dart-style-guide]. |
| 145 | 160 |
| 146 ## Git Commit Guidelines | 161 ## <a name="commit"></a> Git Commit Guidelines |
| 147 | 162 |
| 148 We have very precise rules over how our git commit messages can be formatted. T
his leads to **more | 163 We have very precise rules over how our git commit messages can be formatted. T
his leads to **more |
| 149 readable messages** that are easy to follow when looking through the **project h
istory**. But also, | 164 readable messages** that are easy to follow when looking through the **project h
istory**. But also, |
| 150 we use the git commit messages to **generate the AngularDart change log**. | 165 we use the git commit messages to **generate the AngularDart change log**. |
| 151 | 166 |
| 152 ### Commit Message Format | 167 ### Commit Message Format |
| 153 Each commit message consists of a **header**, a **body** and a **footer**. The
header has a special | 168 Each commit message consists of a **header**, a **body** and a **footer**. The
header has a special |
| 154 format that includes a **type**, a **scope** and a **subject**: | 169 format that includes a **type**, a **scope** and a **subject**: |
| 155 | 170 |
| 156 ``` | 171 ``` |
| (...skipping 36 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 193 Just as in the **subject**, use the imperative, present tense: "change" not "cha
nged" nor "changes" | 208 Just as in the **subject**, use the imperative, present tense: "change" not "cha
nged" nor "changes" |
| 194 The body should include the motivation for the change and contrast this with pre
vious behavior. | 209 The body should include the motivation for the change and contrast this with pre
vious behavior. |
| 195 | 210 |
| 196 ###Footer | 211 ###Footer |
| 197 The footer should contain any information about **Breaking Changes** and is also
the place to | 212 The footer should contain any information about **Breaking Changes** and is also
the place to |
| 198 reference GitHub issues that this commit **Closes**. | 213 reference GitHub issues that this commit **Closes**. |
| 199 | 214 |
| 200 | 215 |
| 201 A detailed explanation can be found in this [document][commit-message-format]. | 216 A detailed explanation can be found in this [document][commit-message-format]. |
| 202 | 217 |
| 203 ## Signing the CLA | 218 ## <a name="cla"></a> Signing the CLA |
| 204 | 219 |
| 205 Please sign our Contributor License Agreement (CLA) before sending pull requests
. For any code | 220 Please sign our Contributor License Agreement (CLA) before sending pull requests
. For any code |
| 206 changes to be accepted, the CLA must be signed. It's a quick process, we promise
! | 221 changes to be accepted, the CLA must be signed. It's a quick process, we promise
! |
| 207 | 222 |
| 208 * For individuals we have a [simple click-through form][individual-cla]. | 223 * For individuals we have a [simple click-through form][individual-cla]. |
| 209 * For corporations we'll need you to | 224 * For corporations we'll need you to |
| 210 [print, sign and one of scan+email, fax or mail the form][corporate-cla]. | 225 [print, sign and one of scan+email, fax or mail the form][corporate-cla]. |
| 211 | 226 |
| 212 | 227 |
| 213 [groups]: https://groups.google.com/forum/#!forum/angular-dart | 228 [coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md |
| 214 [stackoverflow]: http://stackoverflow.com/questions/tagged/angular.dart | |
| 215 [github]: https://github.com/angular/angular.dart | |
| 216 [runnable]: http://runnable.com/ | |
| 217 [unit-testing]: https://www.dartlang.org/articles/dart-unit-tests/ | |
| 218 [doc-comments]: https://www.dartlang.org/articles/doc-comment-guidelines/ | |
| 219 [dart-style-guide]: https://www.dartlang.org/articles/idiomatic-dart/ | |
| 220 [individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html | |
| 221 [corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html | |
| 222 [commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15I
JygNPiHORgU1_OOAqWjiDU5Y/edit# | 229 [commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15I
JygNPiHORgU1_OOAqWjiDU5Y/edit# |
| 223 [communityMilestone]: https://github.com/angular/angular.dart/issues?milestone=1
3&state=open | 230 [communityMilestone]: https://github.com/angular/angular.dart/issues?milestone=1
3&state=open |
| 224 [coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md | 231 [corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html |
| 232 [dart-style-guide]: https://www.dartlang.org/articles/idiomatic-dart/ |
| 225 [dev-doc]: https://github.com/angular/angular.dart/blob/master/DEVELOPER.md | 233 [dev-doc]: https://github.com/angular/angular.dart/blob/master/DEVELOPER.md |
| 234 [doc-comments]: https://www.dartlang.org/articles/doc-comment-guidelines/ |
| 235 [github]: https://github.com/angular/angular.dart |
| 236 [groups]: https://groups.google.com/forum/#!forum/angular-dart |
| 237 [individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html |
| 238 [runnable]: http://runnable.com/ |
| 239 [stackoverflow]: http://stackoverflow.com/questions/tagged/angular.dart |
| 240 [unit-testing]: https://www.dartlang.org/articles/dart-unit-tests/ |
| OLD | NEW |