You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+33-38
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,9 @@
1
1
Contributor Guidelines
2
2
======================
3
3
4
-
Have something you'd like to contribute to **Spring Batch Extensions**? 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.
4
+
Have something you'd like to contribute to **Spring Batch Extensions**? We welcome pull requests,
5
+
but ask that you carefully read this document first to understand how best to submit them;
6
+
what kind of changes are likely to be accepted; and what to expect from the Spring team when evaluating your submission.
5
7
6
8
Please refer back to this document as a checklist before issuing any pull request; this will save time for everyone!
7
9
@@ -11,11 +13,15 @@ Not sure what a *pull request* is, or how to submit one? Take a look at GitHub'
11
13
12
14
## Search the [GitHub Issue Tracker][] first; create an issue if necessary
13
15
14
-
Is there already an issue that addresses your concern? Do a bit of searching in our [GitHub 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.
16
+
Is there already an issue that addresses your concern? Do a bit of searching in our [GitHub Issue Tracker][] to see
17
+
if you can find something similar. If not, please create a new issue before submitting a pull request unless the change
18
+
is truly trivial, e.g. typo fixes, removing compiler warnings, etc.
15
19
16
20
## Sign the contributor license agreement
17
21
18
-
Very important, before we can accept any *Spring Batch contributions*, we will need you to sign the contributor license agreement (CLA). Signing the CLA 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. In order to read and sign the CLA, please go to:
22
+
Very important, before we can accept any *Spring Batch contributions*, we will need you to sign the contributor license agreement (CLA).
23
+
Signing the CLA does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions,
24
+
and you will get an author credit if we do. In order to read and sign the CLA, please go to:
_you should now see 'upstream' in addition to 'origin' where 'upstream' is the *spring-projects*repository from which releases are built_
49
+
_you should now see 'upstream' in addition to 'origin' where 'upstream' is the *spring-projects*repository from which releases are built_
44
50
6.`git fetch --all`
45
51
7.`git branch -a`
46
52
_you should see branches on origin as well as upstream, including 'master'_
47
53
48
54
## A Day in the Life of a Contributor
49
55
50
-
*_Always_ work on topic branches (Typically an issue ID or descriptive identifier as the branch name).
51
-
- For example, to create and switch to a new branch for issue BATCHEXT-123: `git checkout -b BATCHEXT-123`
56
+
*_Always_ work on topic branches (Typically an issue ID or descriptive identifier as the branch name). For example, to create and switch to a new branch for issue BATCH-EXT-123: `git checkout -b BATCH-EXT-123`
52
57
* 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).
53
-
* Please follow the "Commit Guidelines" described in this chapter of Pro Git: [https://progit.org/book/ch5-2.html](https://progit.org/book/ch5-2.html)
54
-
* Then to begin working on another issue (say BATCHEXT-101): `git checkout BATCHEXT-101`. The _-b_ flag is not needed if that branch already exists in your local repository.
55
-
* 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 BATCHEXT-123`
58
+
* Please follow the "Commit Guidelines" described in this chapter of Pro Git: [Distributed Git - Contributing to a Project](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
59
+
* Then to begin working on another issue (say BATCH-EXT-101): `git checkout BATCH-EXT-101`. The _-b_ flag is not needed if that branch already exists in your local repository.
60
+
* 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 BATCH-EXT-123`
56
61
* 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 use `git fetch --all` to sync their local state with all of their remotes.
57
62
* If you grant that collaborator push access to your repository, they can even apply their changes to your branch.
58
-
* When ready for your contribution to be reviewed for potential inclusion in the master branch of the canonical *spring-batch-extensions* repository (what you know as 'upstream'), issue a pull request to the *spring-batch-extensions* repository (for more detail, see [https://help.github.com/send-pull-requests/](https://help.github.com/send-pull-requests/)).
63
+
* When ready for your contribution to be reviewed for potential inclusion in the master branch of the canonical *spring-batch-extensions* repository (what you know as 'upstream'), issue a pull request to the *spring-batch-extensions* repository (for more detail, see [help documentation][]).
59
64
* The project lead may merge your changes into the upstream master 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.
60
-
* A prerequisite for any pull request is that it will be cleanly merge-able with the upstream master'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://progit.org/book/ch3-6.html](https://progit.org/book/ch3-6.html). 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."
65
+
* A prerequisite for any pull request is that it will be cleanly merge-able with the upstream master'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: [Git Branching - 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."
61
66
62
67
## Keeping your Local Code in Sync
63
68
* As mentioned above, you should always work on topic branches (since 'master' is a moving target). However, you do want to always keep your own 'origin' master branch in synch with the 'upstream' master.
64
69
* Within your local working directory, you can sync up all remotes' branches with: `git fetch --all`
65
70
* While on your own local master branch: `git pull upstream master` (which is the equivalent of fetching upstream/master and merging that into the branch you are in currently)
66
-
* Now that you're in synch, switch to the topic branch where you plan to work, e.g.: `git checkout -b BATCHEXT-123`
71
+
* Now that you're in synch, switch to the topic branch where you plan to work, e.g.: `git checkout -b BATCH-EXT-123`
67
72
* When you get to a stopping point: `git commit`
68
73
* If changes have occurred on the upstream/master while you were working you can synch again:
69
74
- Switch back to master: `git checkout master`
70
75
- Then: `git pull upstream master`
71
-
- Switch back to the topic branch: `git checkout BATCHEXT-123` (no -b needed since the branch already exists)
72
-
- Rebase the topic branch to minimize the distance between it and your recently synched master branch: `git rebase master`
73
-
(Again, for more detail see the Pro Git section on rebasing: [https://progit.org/book/ch3-6.html](https://progit.org/book/ch3-6.html))
76
+
- Switch back to the topic branch: `git checkout BATCH-EXT-123` (no -b needed since the branch already exists)
77
+
- Rebase the topic branch to minimize the distance between it and your recently synchronized master branch: `git rebase master`
78
+
(Again, for more detail see the Pro Git section on rebasing: [Git Branching - Rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing))
74
79
***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](https://stackoverflow.com/questions/134882/undoing-a-git-rebase). Once you have published your branch, you need to merge in the master rather than rebasing.
75
80
* 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.
76
81
* Assuming your pull request is merged into the 'upstream' master, you will actually end up pulling that change into your own master 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.
77
-
- to delete the local branch: `git branch -d BATCHEXT-123`
78
-
- to delete the branch from your origin: `git push origin :BATCHEXT-123`
82
+
- to delete the local branch: `git branch -d BATCH-EXT-123`
83
+
- to delete the branch from your origin: `git push origin :BATCH-EXT-123`
79
84
80
85
## Maintain a linear commit history
81
86
@@ -103,24 +108,13 @@ If you see intersecting lines, that usually means that you forgot to rebase you
103
108
104
109
## Mind the whitespace
105
110
106
-
Please carefully follow the whitespace and formatting conventions already present in the framework.
107
-
108
-
1. Tabs, not spaces
109
-
2. Unix (LF), not DOS (CRLF) line endings
110
-
3. Eliminate all trailing whitespace
111
-
4. Wrap Javadoc at 90 characters
112
-
5. Aim to wrap code at 90 characters, but favor readability over wrapping
113
-
6. Preserve existing formatting; i.e. do not reformat code for its own sake
114
-
7. Search the codebase using `git grep` and other tools to discover common
115
-
naming conventions, etc.
116
-
8. Latin-1 (ISO-8859-1) encoding for Java sources; use `native2ascii` to convert
117
-
if necessary
111
+
Please carefully follow the same [code style as Spring Framework](https://github.com/spring-projects/spring-framework/wiki/Code-Style).
118
112
119
113
## Add Apache license header to all new classes
120
114
121
115
```java
122
116
/*
123
-
* Copyright 2002-2014 the original author or authors.
117
+
* Copyright 2002-2021 the original author or authors.
124
118
*
125
119
* Licensed under the Apache License, Version 2.0 (the "License");
126
120
* you may not use this file except in compliance with the License.
@@ -140,16 +134,16 @@ package ...;
140
134
141
135
## Update license header to modified files as necessary
142
136
143
-
Always check the date range in the Apache license header. For example, if you've modified a file in 2014 whose header still reads
137
+
Always check the date range in the Apache license header. For example, if you've modified a file in 2021 whose header still reads
144
138
145
139
```java
146
140
*Copyright2002-2011 the original author or authors.
147
141
```
148
142
149
-
then be sure to update it to 2014 appropriately
143
+
then be sure to update it to 2021 appropriately
150
144
151
145
```java
152
-
*Copyright2002-2014 the original author or authors.
146
+
*Copyright2002-2021 the original author or authors.
153
147
```
154
148
155
149
## Use @since tags
@@ -168,11 +162,12 @@ Use @since tags for newly-added public API types and methods e.g.
168
162
169
163
## Submit JUnit test cases for all behavior changes
170
164
171
-
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 issue basis.
165
+
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 issue basis.
172
166
173
167
## Squash commits
174
168
175
-
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/4_interactive_rebasing.html.
169
+
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,
170
+
there are many resources online to help you understand how these tools work. Here is one: [https://git-scm.com/docs/git-rebase#_interactive_mode](https://git-scm.com/docs/git-rebase#_interactive_mode).
176
171
177
172
## Use your real name in git commits
178
173
@@ -191,9 +186,9 @@ You can configure this globally via the account admin area GitHub (useful for fo
0 commit comments