Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 304 lines (217 sloc) 11.592 kb
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
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 ## Understand the basics
10
11 Not sure what a pull request is, or how to submit one? Take a look at GitHub's
12 excellent [help documentation][] first.
13
14
15 ## Search JIRA first; create an issue if necessary
16
17 Is there already an issue that addresses your concern? Do a bit of searching
18 in our [JIRA issue tracker][] to see if you can find something similar. If not,
19 please create a new issue before submitting a pull request unless the change is
20 truly trivial, e.g. typo fixes, removing compiler warnings, etc.
21
22 ## Discuss non-trivial contribution ideas with committers
23
24 If you're considering anything more than correcting a typo or fixing a minor
25 bug, please discuss it on the [spring-framework-contrib][] mailing list before
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
26 submitting a pull request. We're happy to provide guidance, but please spend an
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
27 hour or two researching the subject on your own including searching the mailing
28 list for prior discussions.
29
30 ## Sign the Contributor License Agreement
31
32 If you have not previously done so, please fill out and submit the
33 [SpringSource CLA form][]. You'll receive a token when this process is complete.
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
34 Keep track of this; you may be asked for it later!
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
35
36 Note that emailing/postal mailing a signed copy is _not_ necessary. Submission
37 of the web form is all that is required.
38
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
39 Once you've completed the web form, simply add the following in a comment on
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
40 your pull request:
41
42 I have signed and agree to the terms of the SpringSource Individual
43 Contributor License Agreement.
44
45 You do not need to include your token/id. Please add the statement above to all
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
46 future pull requests as well, simply so that the Spring Framework team knows
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
47 immediately that this process is complete.
48
49
0758e72 @cbeams Update contributor guidelines regarding 3.2.x branch
cbeams authored
50 ## Create your branch from `3.2.x`
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
51
0758e72 @cbeams Update contributor guidelines regarding 3.2.x branch
cbeams authored
52 If your pull request addresses a bug or improvement, please create your branch
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
53 from Spring Framework's `3.2.x` branch. `master` is reserved for work on new features
0758e72 @cbeams Update contributor guidelines regarding 3.2.x branch
cbeams authored
54 for the next major version of the framework. Rest assured that if your pull
55 request is accepted and merged into `3.2.x`, these changes will also eventually
56 be merged into `master`.
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
57
58
59 ## Use short branch names
60
61 Branches used when submitting pull requests should preferably be named
62 according to JIRA issues, e.g. 'SPR-1234'. Otherwise, use succinct, lower-case,
63 dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In
64 [fork-and-edit][] cases, the GitHub default 'patch-1' is fine as well. This is
65 important, because branch names show up in the merge commits that result from
66 accepting pull requests, and should be as expressive and concise as possible.
67
68
69 ## Mind the whitespace
70
71 Please carefully follow the whitespace and formatting conventions already
72 present in the framework.
73
74 1. Tabs, not spaces
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
75 1. Unix (LF), not DOS (CRLF) line endings
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
76 1. Eliminate all trailing whitespace
77 1. Wrap Javadoc at 90 characters
78 1. Aim to wrap code at 90 characters, but favor readability over wrapping
79 1. Preserve existing formatting; i.e. do not reformat code for its own sake
80 1. Search the codebase using `git grep` and other tools to discover common
81 naming conventions, etc.
82 1. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert
83 if necessary
84
85
86 ## Add Apache license header to all new classes
87
88 ```java
89 /*
94a8806 @philwebb Update example years to 2013 in CONTRIBUTING.md
philwebb authored
90 * Copyright 2002-2013 the original author or authors.
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
91 *
92 * Licensed under the Apache License, Version 2.0 (the "License");
93 * you may not use this file except in compliance with the License.
94 * You may obtain a copy of the License at
95 *
96 * http://www.apache.org/licenses/LICENSE-2.0
97 *
98 * Unless required by applicable law or agreed to in writing, software
99 * distributed under the License is distributed on an "AS IS" BASIS,
100 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
101 * See the License for the specific language governing permissions and
102 * limitations under the License.
103 */
104
105 package ...;
106 ```
107
108 ## Update Apache license header to modified files as necessary
109
110 Always check the date range in the license header. For example, if you've
94a8806 @philwebb Update example years to 2013 in CONTRIBUTING.md
philwebb authored
111 modified a file in 2013 whose header still reads
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
112
113 ```java
114 * Copyright 2002-2011 the original author or authors.
115 ```
116
94a8806 @philwebb Update example years to 2013 in CONTRIBUTING.md
philwebb authored
117 then be sure to update it to 2013 appropriately
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
118
119 ```java
94a8806 @philwebb Update example years to 2013 in CONTRIBUTING.md
philwebb authored
120 * Copyright 2002-2013 the original author or authors.
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
121 ```
122
123 ## Use @since tags for newly-added public API types and methods
124
125 e.g.
126
127 ```java
128 /**
129 * ...
130 *
131 * @author First Last
132 * @since 3.2
133 * @see ...
134 */
135 ```
136
137 ## Submit JUnit test cases for all behavior changes
138
139 Search the codebase to find related unit tests and add additional @Test methods
140 within. It is also acceptable to submit test cases on a per JIRA issue basis,
141 e.g.
142
143 ```java
144 package org.springframework.beans.factory.support;
145
146 /**
147 * Unit tests for SPR-8954, in which a custom {@link InstantiationAwareBeanPostProcessor}
148 * forces the predicted type of a FactoryBean, effectively preventing retrieval of the
149 * bean from calls to #getBeansOfType(FactoryBean.class). The implementation of
150 * {@link AbstractBeanFactory#isFactoryBean(String, RootBeanDefinition)} now ensures
151 * that not only the predicted bean type is considered, but also the original bean
152 * definition's beanClass.
153 *
154 * @author Chris Beams
155 */
156 public class Spr8954Tests {
157
158 @Test
159 public void cornerSpr8954() {
160 // ...
161 }
162 }
163 ```
164
165
166 ## Squash commits
167
168 Use `git rebase --interactive`, `git add --patch` and other tools to "squash"
169 multiple commits into atomic changes. In addition to the man pages for git,
170 there are many resources online to help you understand how these tools work.
171 Here is one: http://book.git-scm.com/4_interactive_rebasing.html.
172
173
174 ## Use real name in git commits
175
176 Please configure git to use your real first and last name for any commits you
177 intend to submit as pull requests. For example, this is not acceptable:
178
179 Author: Nickname <user@mail.com>
180
181 Rather, please include your first and last name, properly capitalized, as
182 submitted against the SpringSource contributor license agreement:
183
184 Author: First Last <user@mail.com>
185
186 This helps ensure traceability against the CLA, and also goes a long way to
187 ensuring useful output from tools like `git shortlog` and others.
188
189 You can configure this globally via the account admin area GitHub (useful for
190 fork-and-edit cases); globally with
191
192 git config --global user.name "First Last"
193 git config --global user.email user@mail.com
194
195 or locally for the spring-framework repository only by omitting the '--global'
196 flag:
197
198 cd spring-framework
199 git config user.name "First Last"
200 git config user.email user@mail.com
201
202
203 ## Format commit messages
204
205 Please read and follow the [commit guidelines section of Pro Git][].
206
207 Most importantly, please format your commit messages in the following way
208 (adapted from the commit template in the link above):
209
210 Short (50 chars or less) summary of changes
211
212 More detailed explanatory text, if necessary. Wrap it to about 72
213 characters or so. In some contexts, the first line is treated as the
214 subject of an email and the rest of the text as the body. The blank
215 line separating the summary from the body is critical (unless you omit
216 the body entirely); tools like rebase can get confused if you run the
217 two together.
218
219 Further paragraphs come after blank lines.
220
221 - Bullet points are okay, too
222
223 - Typically a hyphen or asterisk is used for the bullet, preceded by a
224 single space, with blank lines in between, but conventions vary here
225
226 Issue: SPR-1234, SPR-1235
227
228
229 1. Use imperative statements in the subject line, e.g. "Fix broken Javadoc link"
230 1. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune,
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
231 Fix, Introduce, Avoid, etc."
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
232 1. Do not end the subject line with a period
233 1. Keep the subject line to 50 characters or less if possible
234 1. Wrap lines in the body at 72 characters or less
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
235 1. Mention associated JIRA issue(s) at the end of the commit comment, prefixed
30bce7f @cbeams Add CONTRIBUTING.md
cbeams authored
236 with "Issue: " as above
237 1. In the body of the commit message, explain how things worked before this
238 commit, what has changed, and how things work now
239
240 For examples of this style, issue a `git log --author=cbeams` in the
241 spring-framework git repository. For convenience, here are several such commits:
242
243 https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078
244 https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da
245 https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6
246 https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477
247
248 ## Run all tests prior to submission
249
250 See the [building from source][] section of the README for instructions. Make
251 sure that all tests pass prior to submitting your pull request.
252
253
254 ## Submit your pull request
255
256 Subject line:
257
258 Follow the same conventions for pull request subject lines as mentioned above
259 for commit message subject lines.
260
261 In the body:
262
263 1. Explain your use case. What led you to submit this change? Why were existing
264 mechanisms in the framework insufficient? Make a case that this is a
265 general-purpose problem and that yours is a general-purpose solution, etc.
266 1. Add any additional information and ask questions; start a conversation, or
267 continue one from JIRA
268 1. Mention the JIRA issue ID
269 1. Also mention that you have submitted the CLA as described above
270
271 Note that for pull requests containing a single commit, GitHub will default the
272 subject line and body of the pull request to match the subject line and body of
273 the commit message. This is fine, but please also include the items above in the
274 body of the request.
275
276
277 ## Mention your pull request on the associated JIRA issue
278
279 Add a comment to the associated JIRA issue(s) linking to your new pull request.
280
281
282 ## Expect discussion and rework
283
284 The Spring team takes a very conservative approach to accepting contributions to
285 the framework. This is to keep code quality and stability as high as possible,
286 and to keep complexity at a minimum. Your changes, if accepted, may be heavily
287 modified prior to merging. You will retain "Author:" attribution for your Git
288 commits granted that the bulk of your changes remain intact. You may be asked to
289 rework the submission for style (as explained above) and/or substance. Again, we
290 strongly recommend discussing any serious submissions with the Spring Framework
291 team _prior_ to engaging in serious development work.
292
293 Note that you can always force push (`git push -f`) reworked / rebased commits
294 against the branch used to submit your pull request. i.e. you do not need to
295 issue a new pull request when asked to make changes.
296
297 [help documentation]: http://help.github.com/send-pull-requests
298 [JIRA issue tracker]: https://jira.springsource.org/browse/SPR
299 [spring-framework-contrib]: https://groups.google.com/forum/#!forum/spring-framework-contrib
300 [SpringSource CLA form]: https://support.springsource.com/spring_committer_signup
301 [fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button
302 [commit guidelines section of Pro Git]: http://progit.org/book/ch5-2.html#commit_guidelines
303 [building from source]: https://github.com/SpringSource/spring-framework#building-from-source
Something went wrong with that request. Please try again.