270 lines
10 KiB
Plaintext
270 lines
10 KiB
Plaintext
:wiki-root: https://github.com/spring-projects/spring-framework/wiki
|
||
|
||
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!_
|
||
|
||
[[code-of-conduct]]
|
||
# Code of Conduct
|
||
|
||
This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct].
|
||
By participating you are expected to uphold this code. Please report unacceptable behavior
|
||
to spring-code-of-conduct@pivotal.io.
|
||
|
||
[[take-your-first-steps]]
|
||
# Take Your First Steps
|
||
|
||
[[understand-the-basics]]
|
||
## Understand the basics
|
||
|
||
Not sure what a pull request is, or how to submit one? Take a look at
|
||
GitHub’s excellent
|
||
https://help.github.com/categories/collaborating-on-projects-using-issues-and-pull-requests/[help documentation]
|
||
first.
|
||
|
||
[[search-stack-overflow-first-discuss-if-necessary]]
|
||
## Search Stack Overflow first; discuss if necessary
|
||
|
||
If you’re unsure why something isn’t working or wondering if there is a
|
||
better way of doing it please check on Stack Overflow first and if
|
||
necessary start a discussion. This is the official list of
|
||
https://spring.io/questions[Spring-related tags]. In short the issue
|
||
tracker should be used to report issues and make feature requests.
|
||
|
||
[[search-jira-create-an-issue-if-necessary]]
|
||
## Search JIRA; create an issue if necessary
|
||
|
||
Is there already an issue that addresses your concern? Do a bit of
|
||
searching in our https://jira.spring.io/browse/SPR[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.
|
||
|
||
[[sign-the-contributor-license-agreement-cla]]
|
||
## Sign the Contributor License Agreement (CLA)
|
||
|
||
If you have not previously done so, please sign the
|
||
https://cla.pivotal.io/sign/spring[Contributor License Agreement].
|
||
If you forget to do so, you’ll be reminded when you submit a pull request.
|
||
|
||
[[create-a-branch]]
|
||
# Create a Branch
|
||
|
||
[[branch-from-master]]
|
||
## Branch from `master`
|
||
|
||
Master currently represents work toward Spring Framework 5.0. Please
|
||
submit all pull requests there, even bug fixes and minor improvements.
|
||
Backports to `4.3.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, dash (-) delimited names, such as `fix-warnings',
|
||
`fix-typo', etc. In https://github.com/blog/844-forking-with-the-edit-button[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.
|
||
|
||
[[use-spring-framework-code-style]]
|
||
# Use Spring Framework Code Style
|
||
|
||
The complete
|
||
https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style[Spring Framework Code Style]
|
||
reference is available on the wiki.
|
||
|
||
[[prepare-your-commit]]
|
||
# Prepare Your Commit
|
||
|
||
[[submit-junit-test-cases-for-all-behavior-changes]]
|
||
## Submit JUnit test cases for all behavior changes
|
||
|
||
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:
|
||
|
||
[source,java]
|
||
----
|
||
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]]
|
||
## Squash commits
|
||
|
||
Use `git rebase --interactive --autosquash`, `git add --patch`, and
|
||
other tools to ``squash'' multiple commits into a single atomic commit.
|
||
In addition to the man pages for git, there are many resources online to
|
||
help you understand how these tools work. The
|
||
http://git-scm.com/book/en/Git-Tools-Rewriting-History[Rewriting History section of Pro Git]
|
||
provides a good overview.
|
||
|
||
[[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:
|
||
|
||
....
|
||
Author: Nickname <user@mail.com>
|
||
....
|
||
|
||
Rather, please include your first and last name, properly capitalized,
|
||
as submitted against the Spring Individual Contributor License Agreement
|
||
(ICLA):
|
||
|
||
....
|
||
Author: First Last <user@mail.com>
|
||
....
|
||
|
||
This helps ensure traceability against the ICLA and also goes a long way
|
||
to ensuring useful output from tools like `git shortlog` and others.
|
||
|
||
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:
|
||
|
||
....
|
||
cd spring-framework
|
||
git config user.name "First Last"
|
||
git config user.email user@mail.com
|
||
....
|
||
|
||
[[format-commit-messages]]
|
||
## Format commit messages
|
||
|
||
Please read and follow the
|
||
http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines[Commit Guidelines section of Pro Git].
|
||
|
||
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, SPR-1235
|
||
....
|
||
|
||
1. Use imperative statements in the subject line, e.g. ``Fix broken
|
||
Javadoc link''.
|
||
2. Begin the subject line with a capitalized verb, e.g. ``Add, Prune,
|
||
Fix, Introduce, Avoid, etc.''
|
||
3. Do not end the subject line with a period.
|
||
4. Restrict the subject line to 50 characters or less if possible.
|
||
5. Wrap lines in the body at 72 characters or less.
|
||
6. Mention associated JIRA issue(s) at the end of the commit comment,
|
||
prefixed with ``Issue:'' as above.
|
||
7. 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/spring-projects/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078
|
||
* https://github.com/spring-projects/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da
|
||
* https://github.com/spring-projects/spring-framework/commit/8e0b1c3a5f957af3049cfa0438317177e16d6de6
|
||
* https://github.com/spring-projects/spring-framework/commit/b787a68f2050df179f7036b209aa741230a02477
|
||
|
||
[[run-the-final-checklist]]
|
||
# Run the Final Checklist
|
||
|
||
[[run-all-tests-prior-to-submission]]
|
||
## Run all tests prior to submission
|
||
|
||
See the https://github.com/spring-projects/spring-framework#building-from-source[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:
|
||
|
||
Follow the same conventions for pull request subject lines as mentioned
|
||
above for commit message subject lines.
|
||
|
||
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.
|
||
2. Add any additional information and ask questions; start a
|
||
conversation or continue one from JIRA.
|
||
3. Mention the JIRA issue ID.
|
||
4. Also mention that you have submitted the ICLA as described above.
|
||
|
||
Note that 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, 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, and to keep complexity at a minimum. Your
|
||
changes, if accepted, may be heavily modified prior to 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 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. In other
|
||
words, you do not need to issue a new pull request when asked to make
|
||
changes. |