Polish CONTRIBUTING page
This commit is contained in:
Sam Brannen
parent
2edff2135f
commit
d108db8a79
101
CONTRIBUTING.md
101
CONTRIBUTING.md
|
|
@ -1,32 +1,33 @@
|
|||
_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
|
||||
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!_
|
||||
|
||||
## Take your first steps
|
||||
## 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
|
||||
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
|
||||
|
||||
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.
|
||||
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 you
|
||||
do not find something similar, please create a new JIRA issue before submitting
|
||||
a pull request unless the change is truly trivial -- for example: typo fixes,
|
||||
removing compiler warnings, etc.
|
||||
|
||||
### 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
|
||||
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
|
||||
hour or two researching the subject on your own, including searching the mailing
|
||||
list for prior discussions.
|
||||
|
||||
### Sign the Contributor License Agreement
|
||||
|
|
@ -44,11 +45,11 @@ your pull request:
|
|||
I have signed and agree to the terms of the SpringSource Individual
|
||||
Contributor License Agreement.
|
||||
|
||||
You do not need to include your token/id. Please add the statement above to all
|
||||
You do not need to include your token/id. Please add the above statement 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 a Branch
|
||||
|
||||
### Branch from `master`
|
||||
|
||||
|
|
@ -64,12 +65,12 @@ 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.
|
||||
accepting pull requests and should be as expressive and concise as possible.
|
||||
|
||||
## Use Spring code style
|
||||
## Use Spring Code Style
|
||||
|
||||
The complete [Spring Code Style][] reference is available on the wiki.
|
||||
Here's a quick summary:
|
||||
The complete [Spring Code Style][] reference is available on the wiki, but
|
||||
here's a quick summary:
|
||||
|
||||
### Mind the whitespace
|
||||
|
||||
|
|
@ -83,16 +84,16 @@ present in the framework.
|
|||
1. Aim to wrap code at 90 characters, but favor readability over wrapping
|
||||
1. Preserve existing formatting; i.e. do not reformat code for its own sake
|
||||
1. Search the codebase using `git grep` and other tools to discover common
|
||||
naming conventions, etc.
|
||||
naming conventions, etc.
|
||||
1. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert
|
||||
if necessary
|
||||
if necessary
|
||||
|
||||
|
||||
### Add Apache license header to all new classes
|
||||
|
||||
```java
|
||||
/*
|
||||
* Copyright 2002-2013 the original author or authors.
|
||||
* Copyright 2002-2014 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.
|
||||
|
|
@ -110,24 +111,24 @@ present in the framework.
|
|||
package ...;
|
||||
```
|
||||
|
||||
### Update Apache license header to modified files as necessary
|
||||
### Update Apache license header in 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
|
||||
modified a file in 2014 whose header still reads:
|
||||
|
||||
```java
|
||||
* Copyright 2002-2011 the original author or authors.
|
||||
```
|
||||
|
||||
then be sure to update it to 2013 appropriately
|
||||
Then be sure to update it to 2014 accordingly:
|
||||
|
||||
```java
|
||||
* Copyright 2002-2013 the original author or authors.
|
||||
* Copyright 2002-2014 the original author or authors.
|
||||
```
|
||||
|
||||
### Use @since tags for newly-added public API types and methods
|
||||
|
||||
e.g.
|
||||
For example:
|
||||
|
||||
```java
|
||||
/**
|
||||
|
|
@ -139,13 +140,13 @@ e.g.
|
|||
*/
|
||||
```
|
||||
|
||||
## Prepare your commit
|
||||
## 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,
|
||||
e.g.
|
||||
Search the codebase to find related tests and add additional `@Test` methods
|
||||
as appropriate. It is also acceptable to submit test cases on a per JIRA issue
|
||||
basis, for example:
|
||||
|
||||
```java
|
||||
package org.springframework.beans.factory.support;
|
||||
|
|
@ -172,10 +173,10 @@ public class Spr8954Tests {
|
|||
|
||||
### 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 `git rebase --interactive --autosquash`, `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 real name in git commits
|
||||
|
|
@ -190,17 +191,17 @@ submitted against the SpringSource contributor license agreement:
|
|||
|
||||
Author: First Last <user@mail.com>
|
||||
|
||||
This helps ensure traceability against the CLA, and also goes a long way to
|
||||
This helps ensure traceability against the CLA and also goes a long way to
|
||||
ensuring useful output from tools like `git shortlog` and others.
|
||||
|
||||
You can configure this globally via the account admin area GitHub (useful for
|
||||
fork-and-edit cases); globally with
|
||||
You can configure this via the account admin area in GitHub (useful for
|
||||
fork-and-edit cases); _globally_ on your machine with
|
||||
|
||||
git config --global user.name "First Last"
|
||||
git config --global user.email user@mail.com
|
||||
|
||||
or locally for the spring-framework repository only by omitting the '--global'
|
||||
flag:
|
||||
or _locally_ for the `spring-framework` repository only by omitting the
|
||||
'--global' flag:
|
||||
|
||||
cd spring-framework
|
||||
git config user.name "First Last"
|
||||
|
|
@ -234,29 +235,29 @@ Most importantly, please format your commit messages in the following way
|
|||
|
||||
|
||||
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. Begin the subject line 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. Restrict 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
|
||||
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
|
||||
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:
|
||||
`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
|
||||
- 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 the final checklist
|
||||
## Run the Final Checklist
|
||||
|
||||
### Run all tests prior to submission
|
||||
|
||||
See the [building from source][] section of the README for instructions. Make
|
||||
See the [building from source][] section of the `README` for instructions. Make
|
||||
sure that all tests pass prior to submitting your pull request.
|
||||
|
||||
|
||||
|
|
@ -272,7 +273,7 @@ In the body:
|
|||
1. Explain your use case. What led you to submit this change? Why were existing
|
||||
mechanisms in the framework insufficient? Make a case that this is a
|
||||
general-purpose problem and that yours is a general-purpose solution, etc.
|
||||
1. Add any additional information and ask questions; start a conversation, or
|
||||
1. Add any additional information and ask questions; start a conversation or
|
||||
continue one from JIRA
|
||||
1. Mention the JIRA issue ID
|
||||
1. Also mention that you have submitted the CLA as described above
|
||||
|
|
@ -300,8 +301,8 @@ strongly recommend discussing any serious submissions with the Spring Framework
|
|||
team _prior_ to engaging in 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.
|
||||
against the branch used to submit your pull request. In other words, you do not
|
||||
need to issue a new pull request when asked to make changes.
|
||||
|
||||
[help documentation]: http://help.github.com/send-pull-requests
|
||||
[JIRA issue tracker]: https://jira.springsource.org/browse/SPR
|
||||
|
|
|
|||
Loading…
Reference in New Issue