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
This commit is contained in:
Brian Clozel
parent
0637864b39
commit
11c41993f1
|
|
@ -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
|
||||
|
||||
## Mind the whitespace
|
||||
The complete [Spring Code Style][] reference is available on the wiki.
|
||||
Here's a quick summary:
|
||||
|
||||
### 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue