Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
100644 304 lines (217 sloc) 11.592 kb
30bce7f @cbeams Add
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._
6 _Please refer back to this document as a checklist before issuing any pull
7 request; this will save time for everyone!_
9 ## Understand the basics
11 Not sure what a pull request is, or how to submit one? Take a look at GitHub's
12 excellent [help documentation][] first.
15 ## Search JIRA first; create an issue if necessary
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.
22 ## Discuss non-trivial contribution ideas with committers
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
cbeams authored
27 hour or two researching the subject on your own including searching the mailing
28 list for prior discussions.
30 ## Sign the Contributor License Agreement
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
cbeams authored
36 Note that emailing/postal mailing a signed copy is _not_ necessary. Submission
37 of the web form is all that is required.
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
cbeams authored
40 your pull request:
42 I have signed and agree to the terms of the SpringSource Individual
43 Contributor License Agreement.
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
cbeams authored
47 immediately that this process is complete.
0758e72 @cbeams Update contributor guidelines regarding 3.2.x branch
cbeams authored
50 ## Create your branch from `3.2.x`
30bce7f @cbeams Add
cbeams authored
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
cbeams authored
59 ## Use short branch names
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.
69 ## Mind the whitespace
71 Please carefully follow the whitespace and formatting conventions already
72 present in the framework.
74 1. Tabs, not spaces
11d975b @sbrannen Polish contributor guidelines
sbrannen authored
75 1. Unix (LF), not DOS (CRLF) line endings
30bce7f @cbeams Add
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
86 ## Add Apache license header to all new classes
88 ```java
89 /*
94a8806 @philwebb Update example years to 2013 in
philwebb authored
90 * Copyright 2002-2013 the original author or authors.
30bce7f @cbeams Add
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 *
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 */
105 package ...;
106 ```
108 ## Update Apache license header to modified files as necessary
110 Always check the date range in the license header. For example, if you've
94a8806 @philwebb Update example years to 2013 in
philwebb authored
111 modified a file in 2013 whose header still reads
30bce7f @cbeams Add
cbeams authored
113 ```java
114 * Copyright 2002-2011 the original author or authors.
115 ```
94a8806 @philwebb Update example years to 2013 in
philwebb authored
117 then be sure to update it to 2013 appropriately
30bce7f @cbeams Add
cbeams authored
119 ```java
94a8806 @philwebb Update example years to 2013 in
philwebb authored
120 * Copyright 2002-2013 the original author or authors.
30bce7f @cbeams Add
cbeams authored
121 ```
123 ## Use @since tags for newly-added public API types and methods
125 e.g.
127 ```java
128 /**
129 * ...
130 *
131 * @author First Last
132 * @since 3.2
133 * @see ...
134 */
135 ```
137 ## Submit JUnit test cases for all behavior changes
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.
143 ```java
144 package;
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 {
158 @Test
159 public void cornerSpr8954() {
160 // ...
161 }
162 }
163 ```
166 ## Squash commits
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:
174 ## Use real name in git commits
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:
179 Author: Nickname <>
181 Rather, please include your first and last name, properly capitalized, as
182 submitted against the SpringSource contributor license agreement:
184 Author: First Last <>
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.
189 You can configure this globally via the account admin area GitHub (useful for
190 fork-and-edit cases); globally with
192 git config --global "First Last"
193 git config --global
195 or locally for the spring-framework repository only by omitting the '--global'
196 flag:
198 cd spring-framework
199 git config "First Last"
200 git config
203 ## Format commit messages
205 Please read and follow the [commit guidelines section of Pro Git][].
207 Most importantly, please format your commit messages in the following way
208 (adapted from the commit template in the link above):
210 Short (50 chars or less) summary of changes
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.
219 Further paragraphs come after blank lines.
221 - Bullet points are okay, too
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
226 Issue: SPR-1234, SPR-1235
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
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
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
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:
248 ## Run all tests prior to submission
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.
254 ## Submit your pull request
256 Subject line:
258 Follow the same conventions for pull request subject lines as mentioned above
259 for commit message subject lines.
261 In the body:
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
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.
277 ## Mention your pull request on the associated JIRA issue
279 Add a comment to the associated JIRA issue(s) linking to your new pull request.
282 ## Expect discussion and rework
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.
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.
297 [help documentation]:
298 [JIRA issue tracker]:
299 [spring-framework-contrib]:!forum/spring-framework-contrib
300 [SpringSource CLA form]:
301 [fork-and-edit]:
302 [commit guidelines section of Pro Git]:
303 [building from source]:
Something went wrong with that request. Please try again.