Have something you'd like to contribute to Spring Batch? 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 Batch 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!
Please see our code of conduct.
Please see our Security policy.
Before opening an issue, please do a quick search in Github issues to see if you can find something similar. If not, please read the Issue Reporting section for more details about how to report issues.
Not sure what a pull request is, or how to submit one? Take a look at the excellent GitHub help documentation first. 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 have not previously done so, please fill out and submit the Contributor License Agreement.
- Go to https://github.com/spring-projects/spring-batch
- Hit the "fork" button and choose your own github account as the target
- For more details see https://docs.github.com/en/get-started/quickstart/fork-a-repo
git clone git@github.com:<your-github-username>/spring-batch.gitcd spring-batchgit remote showyou should see only 'origin' - which is the fork you created for your own github accountgit remote add upstream git@github.com:spring-projects/spring-batch.gitgit remote showyou should now see 'upstream' in addition to 'origin' where 'upstream' is the spring-projects repository from which releases are builtgit fetch --allgit branch -ayou should see branches on origin as well as upstream, including 'main'
- Always work on topic branches (Typically use the Github issue ID as the branch name).
- For example, to create and switch to a new branch for issue GH-123:
git checkout -b GH-123
- For example, to create and switch to a new branch for issue GH-123:
- You might be working on several different topic branches at any given time, but when at a stopping point for one of those branches, commit (a local operation).
- Please follow the "Commit Guidelines" described in this chapter of Pro Git: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
- Then to begin working on another issue (say GH-101):
git checkout GH-101. The -b flag is not needed if that branch already exists in your local repository. - When ready to resolve an issue or to collaborate with others, you can push your branch to origin (your fork), e.g.:
git push origin GH-123 - If you want to collaborate with another contributor, have them fork your repository (add it as a remote) and
git fetch <your-username>to grab your branch. Alternatively, they can usegit fetch --allto sync their local state with all of their remotes. - If you grant that collaborator push access to your repository, they can even apply their changes to your branch.
- When ready for your contribution to be reviewed for potential inclusion in the main branch of the canonical spring-batch repository (what you know as 'upstream'), issue a pull request to the spring-projects repository (for more detail, see GitHub help documentation).
- The project lead may merge your changes into the upstream main branch as-is, he may keep the pull request open yet add a comment about something that should be modified, or he might reject the pull request by closing it.
- A prerequisite for any pull request is that it will be cleanly merge-able with the upstream main's current state. This is the responsibility of any contributor. If your pull request cannot be applied cleanly, the project lead will most likely add a comment requesting that you make it merge-able. For a full explanation, see the Pro Git section on rebasing: https://git-scm.com/book/en/v2/Git-Branching-Rebasing. As stated there: "> Often, you’ll do this to make sure your commits apply cleanly on a remote branch — perhaps in a project to which you’re trying to contribute but that you don’t maintain."
- As mentioned above, you should always work on topic branches (since 'main' is a moving target). However, you do want to always keep your own 'origin' main branch in synch with the 'upstream' main.
- Within your local working directory, you can sync up all remotes' branches with:
git fetch --all - While on your own local main branch:
git pull upstream main(which is the equivalent of fetching upstream/main and merging that into the branch you are in currently) - Now that you're in sync, switch to the topic branch where you plan to work, e.g.:
git checkout -b GH-123 - When you get to a stopping point:
git commit - If changes have occurred on the upstream/main while you were working you can synch again:
- Switch back to main:
git checkout main - Then:
git pull upstream main - Switch back to the topic branch:
git checkout GH-123(no -b needed since the branch already exists) - Rebase the topic branch to minimize the distance between it and your recently synched main branch:
git rebase main(Again, for more detail see the Pro Git section on rebasing: https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
- Switch back to main:
- Note You cannot rebase if you have already pushed your branch to your remote because you'd be rewriting history (see 'The Perils of Rebasing' in the article). If you rebase by mistake, you can undo it as discussed in this stackoverflow discussion. Once you have published your branch, you need to merge in the main rather than rebasing.
- Now, if you issue a pull request, it is much more likely to be merged without conflicts. Most likely, any pull request that would produce conflicts will be deferred until the issuer of that pull request makes these adjustments.
- Assuming your pull request is merged into the 'upstream' main, you will actually end up pulling that change into your own main eventually, and at that time, you may decide to delete the topic branch from your local repository and your fork (origin) if you pushed it there.
- to delete the local branch:
git branch -d GH-123 - to delete the branch from your origin:
git push origin :GH-123
- to delete the local branch:
When issuing pull requests, please ensure that your commit history is linear. From the command line you can check this using:
log --graph --pretty=oneline
As this may cause lots of typing, we recommend creating a global alias, e.g. git logg for this:
git config --global alias.logg 'log --graph --pretty=oneline'
This command, will provide the following output, which in this case shows a nice linear history:
* e1f6de38e04a5227fea2d4df193a5b50beaf2d00 GH-2002: Initial support for complex conditional replacements
* 65d2df652abaae2ca309d96e3026c2d67312655f Add ability to set a custom TaskExecutor impl, remove unused namespaces from JSR bootst
* 85807568575c24d8878ad605a344f2bc35bb2b13 Update to allow restart parameters to override previous parameters in JsrJobOperator an
* a21df75ce9dfc92e9768353b827da4248aefe425 GH-2049: Support multiple fragmentRootElementNames in StaxEventItemReader
* 7f1130c9a265a3ce18a46cbbc122e6573167a036 Fix TCK test JobOperatorTests.testJobOperatorRestartJobAlreadyAbandoned
* c4231c4cc861bbcc43437c80a03ddd9b7b2897a3 Fixed no executions returned check and added a unit test
If you see intersecting lines, that usually means that you forgot to rebase you branch. As mentioned earlier, please rebase against main before issuing a pull request.
Please carefully follow the same code style as Spring Framework.
/*
* Copyright 2002-2013 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
*
* https://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 ...;Always check the date range in the Apache license header. For example, if you've modified a file in 2013 whose header still reads
* Copyright 2002-2011 the original author or authors.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 e.g.
/**
* ...
*
* @author First Last
* @since 3.0
* @see ...
*/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 Github issue basis.
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: https://book.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing .
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 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
git config --global user.name "First Last"
git config --global user.email user@mail.com
or locally for the *spring-batch repository only by omitting the '--global' flag:
cd spring-batch
git config user.name "First Last"
git config user.email user@mail.com
See the checking out and building section of the README for instructions. Make sure that all tests pass prior to submitting your pull request.
Add a comment to the associated Github issue(s) linking to your new pull request.