Add contributor guidelines

Contributor-guidelines.md

@@ -0,0 +1,166 @@
+_Have something you'd like to contribute to the framework?  We welcome pull requests, but ask that you carefully read this document first to understand how best to submit them; what kind of changes are likely to be accepted; and what to expect from the Spring team when evaluating your submission._
+
+_Please refer back to this document as a checklist before issuing any pull request; this will save time for everyone!_
+
+## Understand the basics
+
+Not sure what a pull request is, or how to submit one?  Take a look at GitHub's excellent [help documentation](http://help.github.com/send-pull-requests) first.
+
+
+## Search JIRA first; create an issue if necessary
+
+Is there already an issue that addresses your concern?  Do a bit of searching in our [JIRA issue tracker](https://jira.springsource.org/browse/SPR) to see if you can find something similar.  If not, please create a new issue before submitting a pull request unless the change is truly trivial, e.g. typo fixes, removing compiler warnings, etc.
+
+If you're considering any significant change, we recommend proposing and discussing it with the development team in JIRA before putting together a pull request.  This could save you a lot of time!
+
+
+## Sign the Contributor License Agreement
+
+If you have not previously done so, please fill out and submit the [SpringSource CLA form] (https://support.springsource.com/spring_committer_signup).  You'll receive a token when this process is complete.  Keep track of this, you may be asked for it later!  Note that emailing/postal mailing a signed copy is _not_ necessary.  Submission of the web form is all that is required.
+
+
+## Mind the whitespace
+
+Please carefully follow the whitespace and formatting conventions already present in the framework.
+
+1. Tabs, not spaces
+1. Unix (LF), not dos (CRLF) line endings
+1. Eliminate all trailing whitespace
+1. Wrap Javadoc at 90 characters
+1. Aim to wrap code at 90 characters, but favor readability over wrapping
+1. Search the codebase using `git grep` and other tools to discover common naming conventions, etc.
+
+
+## Add Apache license header to all new classes
+
+    /*
+     * Copyright 2002-2012 the original author or authors.
+     *
+     * Licensed under the Apache License, Version 2.0 (the "License");
+     * you may not use this file except in compliance with the License.
+     * You may obtain a copy of the License at
+     *
+     *      http://www.apache.org/licenses/LICENSE-2.0
+     *
+     * Unless required by applicable law or agreed to in writing, software
+     * distributed under the License is distributed on an "AS IS" BASIS,
+     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     * See the License for the specific language governing permissions and
+     * limitations under the License.
+     */
+
+     package ...;
+
+## Use @since tags for newly-added public API types and methods
+
+e.g.
+
+    /**
+     * ...
+     *
+     * @author First Last
+     * @since 3.2
+     * @see ...
+     */ 
+
+
+## Submit JUnit test cases for all behavior changes
+
+Search the codebase to find related unit tests and add additional @Test methods within.  It is also acceptable to submit test cases on a per JIRA issue basis, e.g.
+
+    package org.springframework.beans.factory.support;
+
+    /**
+     * Unit tests for SPR-8954, in which a custom {@link InstantiationAwareBeanPostProcessor}
+     * forces the predicted type of a FactoryBean, effectively preventing retrieval of the
+     * bean from calls to #getBeansOfType(FactoryBean.class). The implementation of
+     * {@link AbstractBeanFactory#isFactoryBean(String, RootBeanDefinition)} now ensures
+     * that not only the predicted bean type is considered, but also the original bean
+     * definition's beanClass.
+     *
+     * @author Chris Beams
+     */
+    public class Spr8954Tests {
+
+        @Test
+        public void cornerSpr8954() {
+            // ...
+        }
+    }
+
+## Squash commits
+
+Use `git rebase --interactive`, `git add --patch` and other tools to "squash" multiple commits into atomic changes.  In addition to the man pages for git, there are many resources online to help you understand how these tools work.  Here is one: http://book.git-scm.com/4_interactive_rebasing.html.
+
+
+## Use short branch names
+
+Branches used when submitting pull requests should preferably be named according to JIRA issues, e.g. 'SPR-1234'.  Otherwise, use succinct, lower-case, dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc.  In fork-and-edit cases, the github default 'patch-1' is fine as well.  This is important, because branch names show up in the merge commits that result from accepting pull requests, and should be as expressive and concise as possible.
+
+
+## Format commit messages
+
+Please read and follow the [commit guidelines section of Pro Git](http://progit.org/book/ch5-2.html#commit_guidelines).
+
+Most importantly, please format your commit messages in the following way (adapted from the commit template in the link above):
+
+    Short (50 chars or less) summary of changes
+
+    More detailed explanatory text, if necessary.  Wrap it to about 72
+    characters or so.  In some contexts, the first line is treated as the
+    subject of an email and the rest of the text as the body.  The blank
+    line separating the summary from the body is critical (unless you omit
+    the body entirely); tools like rebase can get confused if you run the
+    two together.
+
+    Further paragraphs come after blank lines.
+
+     - Bullet points are okay, too
+
+     - Typically a hyphen or asterisk is used for the bullet, preceded by a
+       single space, with blank lines in between, but conventions vary here
+
+    Issue: SPR-1234
+
+
+1. Use imperative statements in the subject line, e.g. "Fix broken Javadoc link"
+1. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune, Fix, Introduce, Avoid, etc"
+1. Do not end the subject line with a period
+1. Keep the subject line to 50 characters or less if possible
+1. Wrap lines in the body at 72 characters or less
+1. Mention associated jira issue(s) at the end of the commit comment, prefixed with "Issue: " as above
+1. In the body of the commit message, explain how things worked before this commit, what has changed, and how things work now
+
+For examples of this style, issue a `git log --author=cbeams` in the spring-framework git repository.  For convenience, here are several such commits:
+
+https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078
+https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da
+https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6
+https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477
+
+## Run all tests prior to submission
+
+See https://github.com/SpringSource/spring-framework#building_from_source for instructions.  Make sure that all tests pass prior to submitting your pull request.
+
+
+## Submit your pull request
+
+For pull requests containing a single commit, GitHub will default the subject line and body of the pull request to match the subject line and body of the commit message.  This is fine.
+
+Otherwise, follow the same conventions for pull request subject lines as mentioned above for commit message subject lines.
+
+1. Add any additional information and ask questions in the body of the pull request
+1. Mention the JIRA issue ID in the body of the pull request
+1. Also mention that you have submitted the CLA as described above
+
+
+## Mention your pull request on the associated JIRA issue
+
+Add a comment to the associated JIRA issue(s) linking to your new pull request.
+
+
+## Expect discussion and rework
+
+The Spring team takes a very conservative approach to accepting contributions to the framework.  This is to keep code quality and stability as high as possible, and to keep complexity at a minimum.  Your changes, if accepted, may be heavily modified prior merging.  You will retain "Author:" attribution for your Git commits granted that the bulk of your changes remain intact.  You may be asked to rework the submission for style (as explained above) and/or substance. Again, we strongly recommend discussing any serious submissions with the Spring Framework team _prior_ to engaging in any serious development work.
+
+Note that you can always force push (`git push -f`) reworked / rebased commits against the branch used to submit your pull request.  i.e. you do not need to issue a new pull request when asked to make changes.

Home.md

@@ -2,5 +2,6 @@
 
 * [README](../spring-framework/#readme)
 * [[Downloading Spring artifacts]]
+* [[Contributor guidelines]]
 * [[Gradle build and release FAQ]]
 * [[SpringSource repository FAQ]]