Contributor Guidelines

Pages 3

Clone this wiki locally

Did you create a custom adapter for Spring Integration that you would like to contribute? Or do you have improvements you would like to contribute to existing Spring Integration Adapters?

We very highly welcome your pull requests, but we ask that you carefully read this document first to understand how best to submit them.

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

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.

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. 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.

For Project, please select Spring Integration. The Project Lead is Gary Russell.

When you've completed the web form, simply add the following in a comment on 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 future pull requests as well, simply so the Spring Framework team knows immediately that this process is complete.

Create your branch from master

At any given time, Spring Framework's master branch represents the version currently under development. For example, if 3.1.1 was the latest Spring Framework release, master represents 3.2.0 development, and the 3.1.x branch represents 3.1.2 development.

Create your topic branch to be submitted as a pull request from master. The Spring team will consider your pull request for backporting to maintenance versions (e.g. 3.1.2) on a case-by-case basis; you don't need to worry about submitting anything for backporting.

Use short branch names

Branches used when submitting pull requests should preferably be named according to JIRA issues, e.g. 'INTEXT-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.

Mind the whitespace

Please carefully follow the whitespace and formatting conventions already present in the framework.

Tabs, not spaces

Unix (LF), not dos (CRLF) line endings

Eliminate all trailing whitespace

Wrap Javadoc at 90 characters

Aim to wrap code at 90 characters, but favor readability over wrapping

Preserve existing formatting; i.e. do not reformat code for its own sake

Search the codebase using git grep and other tools to discover common naming conventions, etc.

Latin-1 (ISO-8859-1) encoding for Java sources; use native2ascii to convert if necessary

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...;

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 2012 whose header still reads

*Copyright2002-2011 the original author or authors.

then be sure to update it to 2012 appropriately

*Copyright2002-2012 the original author or authors.

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.

packageorg.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 */publicclassSpr8954Tests {
@TestpublicvoidcornerSpr8954() {
// ...
}
}

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 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 SpringSource contributor license agreement:

Author: First Last <user@mail.com>

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

Format commit messages

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

Submit your pull request

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

Add any additional information and ask questions; start a conversation, or continue one from JIRA

Mention the JIRA issue ID

Also mention that you have submitted the CLA 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

Add a comment to the associated JIRA issue(s) linking to your new pull request.

Expect discussion and rework

The Spring Integration 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. i.e. you do not need to issue a new pull request when asked to make changes.