Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update documentation with coding guidelines

This commit:
* adds a reference to the Spring Code Style wiki page in the main
CONTRIBUTING document
* updates the link to the Spring team in README
* adds a note regarding Intellij IDEA 13 issues
  • Loading branch information...
commit 11c41993f1654631a4cc9162404107f76bc5a949 1 parent 0637864
@bclozel bclozel authored
Showing with 34 additions and 21 deletions.
  1. +30 −18 CONTRIBUTING.md
  2. +1 −1  README.md
  3. +3 −2 import-into-idea.md
View
48 CONTRIBUTING.md
@@ -6,20 +6,22 @@ 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
+## Take your first steps
+
+### Understand the basics
Not sure what a pull request is, or how to submit one? Take a look at GitHub's
excellent [help documentation][] first.
-## Search JIRA first; create an issue if necessary
+### 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][] 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.
-## Discuss non-trivial contribution ideas with committers
+### Discuss non-trivial contribution ideas with committers
If you're considering anything more than correcting a typo or fixing a minor
bug, please discuss it on the [spring-framework-contrib][] mailing list before
@@ -27,7 +29,7 @@ submitting a pull request. We're happy to provide guidance, but please spend an
hour or two researching the subject on your own including searching the mailing
list for prior discussions.
-## Sign the Contributor License Agreement
+### Sign the Contributor License Agreement
If you have not previously done so, please fill out and submit the
[SpringSource CLA form][]. You'll receive a token when this process is complete.
@@ -46,15 +48,16 @@ You do not need to include your token/id. Please add the statement above to all
future pull requests as well, simply so that the Spring Framework team knows
immediately that this process is complete.
+## Create a branch
-## Create your branch from `master`
+### Branch from `master`
Master currently represents work toward Spring Framework 4.0. Please submit
all pull requests there, even bug fixes and minor improvements. Backports to
`3.2.x` will be considered on a case-by-case basis.
-## Use short branch names
+### 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,
@@ -63,8 +66,12 @@ dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In
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.
+## Use Spring code style
+
+The complete [Spring Code Style][] reference is available on the wiki.
+Here's a quick summary:
-## Mind the whitespace
+### Mind the whitespace
Please carefully follow the whitespace and formatting conventions already
present in the framework.
@@ -81,7 +88,7 @@ present in the framework.
if necessary
-## Add Apache license header to all new classes
+### Add Apache license header to all new classes
```java
/*
@@ -103,7 +110,7 @@ present in the framework.
package ...;
```
-## Update Apache license header to modified files as necessary
+### Update Apache license header to modified files as necessary
Always check the date range in the license header. For example, if you've
modified a file in 2013 whose header still reads
@@ -118,7 +125,7 @@ then be sure to update it to 2013 appropriately
* Copyright 2002-2013 the original author or authors.
```
-## Use @since tags for newly-added public API types and methods
+### Use @since tags for newly-added public API types and methods
e.g.
@@ -132,7 +139,9 @@ e.g.
*/
```
-## Submit JUnit test cases for all behavior changes
+## Prepare your commit
+
+### 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,
@@ -161,7 +170,7 @@ public class Spr8954Tests {
```
-## Squash commits
+### 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,
@@ -169,7 +178,7 @@ 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 real name in git commits
+### Use real name in git commits
Please configure git to use your real first and last name for any commits you
intend to submit as pull requests. For example, this is not acceptable:
@@ -198,7 +207,7 @@ flag:
git config user.email user@mail.com
-## Format commit messages
+### Format commit messages
Please read and follow the [commit guidelines section of Pro Git][].
@@ -243,13 +252,15 @@ https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02
https://github.com/SpringSource/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6
https://github.com/SpringSource/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477
-## Run all tests prior to submission
+## Run the final checklist
+
+### Run all tests prior to submission
See the [building from source][] section of the README for instructions. Make
sure that all tests pass prior to submitting your pull request.
-## Submit your pull request
+### Submit your pull request
Subject line:
@@ -272,12 +283,12 @@ the commit message. This is fine, but please also include the items above in the
body of the request.
-## Mention your pull request on the associated JIRA issue
+### 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
+### 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,
@@ -297,5 +308,6 @@ issue a new pull request when asked to make changes.
[spring-framework-contrib]: https://groups.google.com/forum/#!forum/spring-framework-contrib
[SpringSource CLA form]: https://support.springsource.com/spring_committer_signup
[fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button
+[Spring Code Style]: https://github.com/spring-projects/spring-framework/wiki/Spring-Code-Style
[commit guidelines section of Pro Git]: http://progit.org/book/ch5-2.html#commit_guidelines
[building from source]: https://github.com/SpringSource/spring-framework#building-from-source
View
2  README.md
@@ -95,7 +95,7 @@ The Spring Framework is released under version 2.0 of the [Apache License][].
[Pull requests]: http://help.github.com/send-pull-requests
[contributor guidelines]: https://github.com/SpringSource/spring-framework/blob/master/CONTRIBUTING.md
[@springframework]: http://twitter.com/springframework
-[team members]: http://twitter.com/springframework/team/members
+[team members]: http://spring.io/team
[team blog]: http://blog.springsource.org
[news feed]: http://www.springsource.org/news-events
[Apache License]: http://www.apache.org/licenses/LICENSE-2.0
View
5 import-into-idea.md
@@ -12,10 +12,11 @@ _Within your locally cloned spring-framework working directory:_
## Known issues
-1. `spring-aspects` does not compile out of the box due to references to aspect types unknown to IDEA.
+1. Those steps don't work currently for Intellij IDEA 13+
+2. `spring-aspects` does not compile out of the box due to references to aspect types unknown to IDEA.
See http://youtrack.jetbrains.com/issue/IDEA-64446 for details. In the meantime, the 'spring-aspects'
module has been excluded from the overall project to avoid compilation errors.
-2. While all JUnit tests pass from the command line with Gradle, many will fail when run from IDEA.
+3. While all JUnit tests pass from the command line with Gradle, many will fail when run from IDEA.
Resolving this is a work in progress. If attempting to run all JUnit tests from within IDEA, you will
likely need to set the following VM options to avoid out of memory errors:
-XX:MaxPermSize=2048m -Xmx2048m -XX:MaxHeapSize=2048m
Please sign in to comment.
Something went wrong with that request. Please try again.