1 | _Have something you'd like to contribute to the framework? We welcome pull
|
2 | requests, but ask that you carefully read this document first to understand how
|
3 | best to submit them; what kind of changes are likely to be accepted; and what
|
4 | to expect from the Spring team when evaluating your submission._
|
5 |
|
6 | _Please refer back to this document as a checklist before issuing any pull
|
7 | request; this will save time for everyone!_
|
8 |
|
9 |
|
10 | ## Understand the basics
|
11 |
|
12 | Not sure what a pull request is, or how to submit one? Take a look at GitHub's
|
13 | excellent [help documentation][] first.
|
14 |
|
15 |
|
16 | ## Search GitHub issues first; create an issue if necessary
|
17 |
|
18 | Is there already an issue that addresses your concern? Do a bit of searching
|
19 | in our [issue tracker][] to see if you can find something similar. If not,
|
20 | please create a new issue before submitting a pull request unless the change is
|
21 | truly trivial, e.g. typo fixes, removing compiler warnings, etc.
|
22 |
|
23 |
|
24 | ## Discuss non-trivial contribution ideas with committers
|
25 |
|
26 | If you're considering anything more than correcting a typo or fixing a minor
|
27 | bug, please discuss it on the [s2js-contrib][] mailing list before submitting a
|
28 | pull request. We're happy to provide guidance but please research the subject
|
29 | on your own including searching the mailing list for prior discussions.
|
30 |
|
31 |
|
32 | ## Sign the Contributor License Agreement
|
33 |
|
34 | If you have not previously done so, please fill out and submit the
|
35 | [s2js CLA form][]. You'll receive a token when this process is complete. Keep
|
36 | track of this; you may be asked for it later!
|
37 |
|
38 | Note that emailing/postal mailing a signed copy is _not_ necessary. Submission
|
39 | of the web form is all that is required.
|
40 |
|
41 | Once you've completed the web form, simply add the following in a comment on
|
42 | your pull request:
|
43 |
|
44 | I have signed and agree to the terms of the s2js Contributor License
|
45 | Agreement.
|
46 |
|
47 | You do not need to include your token/id. Please add the statement above to all
|
48 | future pull requests as well, simply so that the team knows immediately that
|
49 | this process is complete.
|
50 |
|
51 |
|
52 | ## Create your branch from `dev`
|
53 |
|
54 | At any given time, the `master` branch represents the latest stable release and
|
55 | the `dev` branch the version currently under development. For example, if 3.1.1
|
56 | was the latest release, `master` represents 3.1.1 while `dev` is 3.2.0
|
57 | development. There may also be a `3.1.x` branch representing 3.1.2 development.
|
58 |
|
59 | Create your topic branch to be submitted as a pull request from `dev`. The
|
60 | team will consider your pull request for backporting to maintenance versions
|
61 | (e.g. 3.1.2) on a case-by-case basis; you don't need to worry about submitting
|
62 | anything for backporting.
|
63 |
|
64 |
|
65 | ## Use short branch names
|
66 |
|
67 | Branches used when submitting pull requests should use succinct, lower-case,
|
68 | dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In
|
69 | [fork-and-edit][] cases, the GitHub default 'patch-1' is fine as well. This is
|
70 | important, because branch names show up in the merge commits that result from
|
71 | accepting pull requests, and should be as expressive and concise as possible.
|
72 |
|
73 |
|
74 | ## Mind the whitespace
|
75 |
|
76 | Please carefully follow the whitespace and formatting conventions already
|
77 | present in the framework.
|
78 |
|
79 | 1. Tabs, not spaces
|
80 | 1. Unix (LF), not dos (CRLF) line endings
|
81 | 1. Eliminate all trailing whitespace
|
82 | 1. Wrap JSDoc at 80 characters
|
83 | 1. Aim to wrap code at 80 characters, but favor readability over wrapping
|
84 | 1. Preserve existing formatting; i.e. do not reformat code for its own sake
|
85 | 1. Search the codebase using `git grep` and other tools to discover common
|
86 | naming conventions, etc.
|
87 | 1. ascii encoding for JS sources, escape special characters
|
88 |
|
89 |
|
90 | ## Add MIT license header to all new source files
|
91 |
|
92 | ```javascript
|
93 | /*
|
94 | * Copyright (c) 2013 VMware, Inc. All Rights Reserved.
|
95 | *
|
96 | * Permission is hereby granted, free of charge, to any person obtaining a copy
|
97 | * of this software and associated documentation files (the "Software"), to
|
98 | * deal in the Software without restriction, including without limitation the
|
99 | * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
100 | * sell copies of the Software, and to permit persons to whom the Software is
|
101 | * furnished to do so, subject to the following conditions:
|
102 | *
|
103 | * The above copyright notice and this permission notice shall be included in
|
104 | * all copies or substantial portions of the Software.
|
105 | *
|
106 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
107 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
108 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
109 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
110 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
111 | * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
112 | * IN THE SOFTWARE.
|
113 | */
|
114 | ```
|
115 |
|
116 |
|
117 | ## Update license header to modified files as necessary
|
118 |
|
119 | Always check the date range in the license header. For example, if you've
|
120 | modified a file in 2013 whose header still reads
|
121 |
|
122 | ```javascript
|
123 | * Copyright (c) 2012 VMware, Inc.
|
124 | ```
|
125 |
|
126 | then be sure to update it to 2013 appropriately
|
127 |
|
128 | ```javascript
|
129 | * Copyright (c) 2012-2013 VMware, Inc.
|
130 | ```
|
131 |
|
132 |
|
133 | ## Use @since tags for newly-added public API types and methods
|
134 |
|
135 | e.g.
|
136 |
|
137 | ```javascript
|
138 | /**
|
139 | * ...
|
140 | *
|
141 | * @author First Last
|
142 | * @since 3.2
|
143 | * @see ...
|
144 | */
|
145 | ```
|
146 |
|
147 |
|
148 | ## Submit unit test cases for all behavior changes
|
149 |
|
150 | Search the codebase to find related unit tests and add additional test methods.
|
151 | Create new test cases for new modules.
|
152 |
|
153 |
|
154 | ## Squash commits
|
155 |
|
156 | Use `git rebase --interactive`, `git add --patch` and other tools to "squash"
|
157 | multiple commits into atomic changes. In addition to the man pages for git,
|
158 | there are many resources online to help you understand how these tools work.
|
159 | Here is one: http://book.git-scm.com/4_interactive_rebasing.html.
|
160 |
|
161 |
|
162 | ## Use real name in git commits
|
163 |
|
164 | Please configure git to use your real first and last name for any commits you
|
165 | intend to submit as pull requests. For example, this is not acceptable:
|
166 |
|
167 | Author: Nickname <user@mail.com>
|
168 |
|
169 | Rather, please include your first and last name, properly capitalized, as
|
170 | submitted against the SpringSource contributor license agreement:
|
171 |
|
172 | Author: First Last <user@mail.com>
|
173 |
|
174 | This helps ensure traceability against the CLA, and also goes a long way to
|
175 | ensuring useful output from tools like `git shortlog` and others.
|
176 |
|
177 | You can configure this globally via the account admin area GitHub (useful for
|
178 | fork-and-edit cases); globally with
|
179 |
|
180 | git config --global user.name "First Last"
|
181 | git config --global user.email user@mail.com
|
182 |
|
183 | or for the local repository only by omitting the '--global' flag:
|
184 |
|
185 | git config user.name "First Last"
|
186 | git config user.email user@mail.com
|
187 |
|
188 |
|
189 | ## Format commit messages
|
190 |
|
191 | Please read and follow the [commit guidelines section of Pro Git][].
|
192 |
|
193 | Most importantly, please format your commit messages in the following way
|
194 | (adapted from the commit template in the link above):
|
195 |
|
196 | Short (50 chars or less) summary of changes
|
197 |
|
198 | More detailed explanatory text, if necessary. Wrap it to about 72
|
199 | characters or so. In some contexts, the first line is treated as the
|
200 | subject of an email and the rest of the text as the body. The blank
|
201 | line separating the summary from the body is critical (unless you omit
|
202 | the body entirely); tools like rebase can get confused if you run the
|
203 | two together.
|
204 |
|
205 | Further paragraphs come after blank lines.
|
206 |
|
207 | - Bullet points are okay, too
|
208 |
|
209 | - Typically a hyphen or asterisk is used for the bullet, preceded by a
|
210 | single space, with blank lines in between, but conventions vary here
|
211 |
|
212 | Issue: #9
|
213 |
|
214 |
|
215 | 1. Use imperative statements in the subject line, e.g. "Fix broken JSDoc link"
|
216 | 1. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune,
|
217 | Fix, Introduce, Avoid, etc"
|
218 | 1. Do not end the subject line with a period
|
219 | 1. Keep the subject line to 50 characters or less if possible
|
220 | 1. Wrap lines in the body at 72 characters or less
|
221 | 1. Mention associated issue(s) at the end of the commit comment, prefixed
|
222 | with "Issue: " as above
|
223 | 1. In the body of the commit message, explain how things worked before this
|
224 | commit, what has changed, and how things work now
|
225 |
|
226 | For examples of this style, issue a `git log --author=cbeams` in the
|
227 | spring-framework git repository. For convenience, here are several such commits:
|
228 |
|
229 | https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078
|
230 | https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da
|
231 | https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6
|
232 | https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477
|
233 |
|
234 |
|
235 | ## Run all tests prior to submission
|
236 |
|
237 | See the building from source section of the README for instructions. Make sure
|
238 | that all tests pass prior to submitting your pull request.
|
239 |
|
240 |
|
241 | ## Submit your pull request
|
242 |
|
243 | Subject line:
|
244 |
|
245 | Follow the same conventions for pull request subject lines as mentioned above
|
246 | for commit message subject lines.
|
247 |
|
248 | In the body:
|
249 |
|
250 | 1. Explain your use case. What led you to submit this change? Why were existing
|
251 | mechanisms in the framework insufficient? Make a case that this is a
|
252 | general-purpose problem and that yours is a general-purpose solution, etc.
|
253 | 1. Add any additional information and ask questions; start a conversation, or
|
254 | continue one from an existing issue
|
255 | 1. Mention the issue ID
|
256 | 1. Also mention that you have submitted the CLA as described above
|
257 |
|
258 | Note that for pull requests containing a single commit, GitHub will default the
|
259 | subject line and body of the pull request to match the subject line and body of
|
260 | the commit message. This is fine, but please also include the items above in the
|
261 | body of the request.
|
262 |
|
263 |
|
264 | ## Mention your pull request on the associated issue
|
265 |
|
266 | Add a comment to the associated issue(s) linking to your new pull request.
|
267 |
|
268 |
|
269 | ## Expect discussion and rework
|
270 |
|
271 | The Spring team takes a very conservative approach to accepting contributions to
|
272 | the framework. This is to keep code quality and stability as high as possible,
|
273 | and to keep complexity at a minimum. Your changes, if accepted, may be heavily
|
274 | modified prior to merging. You will retain "Author:" attribution for your Git
|
275 | commits granted that the bulk of your changes remain intact. You may be asked to
|
276 | rework the submission for style (as explained above) and/or substance. Again, we
|
277 | strongly recommend discussing any serious submissions with the team _prior_ to
|
278 | engaging in serious development work.
|
279 |
|
280 | Note that you can always force push (`git push -f`) reworked / rebased commits
|
281 | against the branch used to submit your pull request. i.e. you do not need to
|
282 | issue a new pull request when asked to make changes.
|
283 |
|
284 |
|
285 | [help documentation]: http://help.github.com/send-pull-requests
|
286 | [issue tracker]: https://github.com/s2js/rest/issues
|
287 | [s2js-contrib]: https://groups.google.com/forum/#!forum/s2js-contrib
|
288 | [s2js CLA form]: http://support.springsource.com/spring_s2js_signup
|
289 | [fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button
|
290 | [commit guidelines section of Pro Git]: http://progit.org/book/ch5-2.html#commit_guidelines
|