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 |