Contributing

Quickstart

For the impatient, if you want to submit a quick pull request:

• Make sure there is a ticket in the bug tracker for the project in project issues section.
• Make sure you use the code formatters provided https://github.com/spring-projects/spring-data-build/tree/master/etc/ide[here] and have them applied to your changes. Don't submit any formatting related changes.
• Make sure you submit test cases (unit or integration tests) that back your changes.
• Try to reuse existing test sample code (domain classes). Try not to amend existing test cases but create new ones dedicated to the changes you're making to the codebase. Try to test as locally as possible but potentially also add integration tests.
• In the Javadoc for the newly added test cases refer to the issue the changes apply to like this

[source, java]

@Test // DATA…-??? public void yourTestMethod() { … }

• Make sure you added yourself as author in the headers of the classes you touched. Amend the date range in the header if needed.
• Make sure you follow the commit-messages guidelines.
• Make sure you provide your full name and an email address registered with your GitHub account.

Commit messages

The commit message should follow the following style:

• First line starts with the issue id.
• Separate issue id and summary with a dash.
• Start summary with a capital letter.
• Finish summary with a dot.
• In the description, don't use single line breaks. No manual wrapping. Separate paragraphs by a blank line.
• During merges, add a reference to the original pull request.
• Add related references at the very bottom (also see the section on pull requests below).

[source]

DATA…-??? - Summary of the commit (try to stay under 80 characters).

Additional explanations if necessary.

Original pull request: #??. Related tickets: DATA…-???. (optionally refer to related tickets)

Advanced

This section contains some advanced information, mainly targeted at developers of the individual repositories.

General

• Fix bugs in master first, if it's reasonable to port the fix back into a bugfix branch, try to do so with cherry picking.
• Try to keep the lifespan of a feature branch as short as possible. For simple bug fixes they should only be used for code review in pull requests.
• On longer running feature branches, don't pull changes that were made to master in the meantime. Instead, rebase the feature branch onto current master, sorting out issues and making sure the branch will fast-forward merge eventually.

Dependency management

• When upgrading dependencies of a project, make sure you apply the following rules: ** For service releases of a release train only upgrades to bugfix versions are allowed. I.e. if a GA release of a release train included a dependency in version 2.6.2, you must only upgrade to 2.6.x versions. Upgrading to 2.7 is not allowed. ** During the milestone phase of a new release train, upgrade to the latest version of a dependency unless compatibility with a former version is required. Upgrades to new major versions are allowed, too, but consider ways to support multiple major versions for one release train to allow a smoother transition.

Change tracking

• Make sure you don't commit without referring to a issue. If we have a rather general task to work on, create a issue for it and commit against that one.
• Try to resolve a issue in a single commit. I.e. don't have separate commits for the fix and the test cases. When polishing pull requests requires some more effort, have a separate commit to clearly document the polishing (and attribute the efforts to you).
• We usually use feature branches to work on tickets and potentially let multiple people work on a feature.
• Follow the commit message style described in quickstart. Especially the summary line should adhere to the style documented there.
• After pushing fixes to the remote repository, mark the issues as resolved and set the fixed versions according to which branches you pushed to.
• Avoid merge commits as they just tend to make it hard to understand what comes from where. Using the issue identifier in the summary line will allow us to keep track for commits belonging together.

Code style

This section contains some stuff that the IDE formatters do not enforce. Try to keep track of those as well

• Make sure, your IDE uses .* imports for all static ones.
• Eclipse users should activate Save Actions to format sources on save, organize imports and also enable the standard set of
• For methods only consisting of a single line, don't use any blank lines around the line of code. For methods consisting of more than one line of code, have a blank line after the method signature.

Handling pull requests

• Be polite. It might be the first time someone contributes to an OpenSource project so we should forgive violations to the contribution guidelines. Use some gut feeling to find out in how far it makes sense to ask the reporter to fix stuff or just go ahead and add a polishing commit yourself.
• Before we accept a non-trivial patch or pull request we will need you to https://cla.pivotal.io/sign/spring[sign the Contributor License Agreement]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request.
• If you decide to merge stuff back make sure that all the infrastructure requirements are met (set up a JIRA ticket to commit against if necessary, etc.).
• Before merging stuff back into master, make sure you rebase the branch. We generally do not allow merge commits, so a merge should always be fast-forward. The ticket IDs and the timestamps give enough tracking information already.
• The simplest way to merge back a pull request submitted by someone external is curling the patch into git am. You can then polish it by either adding a commit or amending the provided commit. Make sure you keep the original author when amending.

[source]

curl $PULL_REQUEST_URL.patch | git am --ignore-whitespace

• If the you merge back a feature branch and multiple developers contributed to that, try to rearrange to commits and squash the into a single commit per developer. Combine the commit messages and edit them to make sense.
• Before pushing the changes to the remote repository, amend the commit(s) to be pushed and add a reference to the pull request to them. This will cause the pull request UI in GitHub show and link those commits.

[source]

…

Original pull request: #??.

Important pieces here: colon and the sentence completed with a dot.