Improve the issue reporting process

This commit adds a set of guidelines to report issues.

Related to: #4329

Author: fmbenhassine

.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,7 +11,7 @@ Please do a quick search on Github issues first, there might be already a duplic
 If the bug is trivial, just go ahead and create the issue. Otherwise, please take a few moments and fill in the following sections:
 
 **Bug description**
-A clear and concise description of what the bug is.
+A clear and concise description of what the bug is about.
 
 **Environment**
 Please provide as many details as possible: Spring Batch version, Java version, which database you use if any, etc
@@ -23,5 +23,5 @@ Steps to reproduce the issue.
 A clear and concise description of what you expected to happen.
 
 **Minimal Complete Reproducible example**
-Please provide a failing unit test or a [minimal complete example](https://stackoverflow.com/help/minimal-reproducible-example) that reproduces the issue.
+Please provide a failing test or a [minimal complete verifiable example](https://github.com/spring-projects/spring-batch/blob/main/ISSUE_REPORTING.md) that reproduces the issue.
 Bug reports that are reproducible will take priority in resolution over reports that are not reproducible.

CONTRIBUTING.md

@@ -1,7 +1,9 @@
 Contributor Guidelines
 ======================
 
-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 team when evaluating your submission.
+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!
 
@@ -13,26 +15,29 @@ Please see our [code of conduct](https://github.com/spring-projects/.github/blob
 
 Please see our [Security policy](https://github.com/spring-projects/spring-batch/security/policy).
 
-## Understand the basics
+## Reporting issues
 
-Not sure what a *pull request* is, or how to submit one?  Take a look at the excellent [GitHub help documentation][] first.
+Is there already an issue that addresses your concern? Please do a quick search in [Github issues][] to see if you can find something similar.
+If not, please read the [Issue Reporting](https://github.com/spring-projects/spring-batch/blob/main/ISSUE_REPORTING.md) section for more details
+about how to report issues.
 
-## Search Github issues first; create an issue if necessary
+## Contributing through Pull Requests on GitHub
 
-Is there already an issue that addresses your concern?  Do a bit of searching in [Github issues][] 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.
+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.
 
-## Sign the contributor license agreement
+### Sign the contributor license agreement
 
 If you have not previously done so, please fill out and
 submit the [Contributor License Agreement](https://cla.pivotal.io/sign/spring).
 
-## Fork the Repository
+### Fork the Repository
 
 1. Go to [https://github.com/spring-projects/spring-batch](https://github.com/spring-projects/spring-batch)
 2. Hit the "fork" button and choose your own github account as the target
-3. For more details see [https://help.github.com/fork-a-repo/](https://help.github.com/fork-a-repo/)
+3. For more details see [https://docs.github.com/en/get-started/quickstart/fork-a-repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
 
-## Setup your Local Development Environment
+### Setup your Local Development Environment
 
 1. `git clone [email protected]:<your-github-username>/spring-batch.git`
 2. `cd spring-batch`
@@ -45,14 +50,14 @@ _you should now see 'upstream' in addition to 'origin' where 'upstream' is the *
 7. `git branch -a`
 _you should see branches on origin as well as upstream, including 'main'_
 
-## A Day in the Life of a Contributor
+### A Day in the Life of a Contributor
 
 * _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 BATCH-123: `git checkout -b BATCH-123`
+  - For example, to create and switch to a new branch for issue GH-123: `git checkout -b 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](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
-* Then to begin working on another issue (say BATCH-101): `git checkout BATCH-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 BATCH-123`
+* 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 use `git fetch --all` to 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][]).
@@ -63,21 +68,21 @@ _you should see branches on origin as well as upstream, including 'main'_
 * 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 synch, switch to the topic branch where you plan to work, e.g.: `git checkout -b BATCH-123`
+* 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 BATCH-123` (no -b needed since the branch already exists)
+    - 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](https://git-scm.com/book/en/v2/Git-Branching-Rebasing))
 * **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 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 BATCH-123`
-    - to delete the branch from your origin: `git push origin :BATCH-123`
+    - to delete the local branch: `git branch -d GH-123`
+    - to delete the branch from your origin: `git push origin :GH-123`
 
-## Maintain a linear commit history
+### Maintain a linear commit history
 
 When issuing pull requests, please ensure that your commit history is linear. From the command line you can check this using:
 
@@ -94,20 +99,20 @@ 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 BATCH-2002: Initial support for complex conditional replacements
+* 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 BATCH-2049: Support multiple fragmentRootElementNames in StaxEventItemReader
+* 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.
 
-## Code style
+### Code style
 
 Please carefully follow the same [code style as Spring Framework](https://github.com/spring-projects/spring-framework/wiki/Code-Style).
 
-## Add Apache license header to all new classes
+### Add Apache license header to all new classes
 
 ```java
 /*
@@ -129,7 +134,7 @@ Please carefully follow the same [code style as Spring Framework](https://github
 package ...;
 ```
 
-## Update license header to modified files as necessary
+### Update license header to modified files as necessary
 
 Always check the date range in the Apache license header. For example, if you've modified a file in 2013 whose header still reads
 
@@ -143,7 +148,7 @@ then be sure to update it to 2013 appropriately
  * Copyright 2002-2013 the original author or authors.
 ```
 
-## Use @since tags
+### Use @since tags
 
 Use @since tags for newly-added public API types and methods e.g.
 
@@ -157,15 +162,15 @@ Use @since tags for newly-added public API types and methods e.g.
  */
 ```
 
-## Submit JUnit test cases for all behavior changes
+### 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 Github issue basis.
 
-## Squash commits
+### 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: https://book.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing .
 
-## Use your real name in git commits
+### Use your 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:
 
@@ -188,11 +193,11 @@ or locally for the *spring-batch repository only by omitting the '--global' flag
     git config user.name "First Last"
     git config user.email [email protected]
 
-## Run all tests prior to submission
+### Run all tests prior to submission
 
 See the [checking out and building][] section of the README for instructions. Make sure that all tests pass prior to submitting your pull request.
 
-## Mention your pull request on the associated Github issue
+### Mention your pull request on the associated Github issue
 
 Add a comment to the associated Github issue(s) linking to your new pull request.
 

ISSUE_REPORTING.md

@@ -0,0 +1,69 @@
+# Issue reporting Guidelines
+
+Thank you very much for taking the time to report a bug to us, we greatly appreciate it! This document is designed to allow Spring Batch users and team members to contribute self-contained projects containing [minimal complete verifiable examples](https://en.wikipedia.org/wiki/Minimal_reproducible_example) for issues logged against the [issue tracker](https://github.com/spring-projects/spring-batch/issues) on GitHub.
+
+Our goal is to have a streamlined process for evaluating issues so bugs get fixed more quickly!
+
+# Downloading the minimal complete verifiable example
+
+We provide a minimal complete verifiable example that you can download here: [spring-batch-mcve.zip](https://raw.githubusercontent.com/wiki/spring-projects/spring-batch/mcve/spring-batch-mcve.zip). This example provides a starting point that you need to edit, zip and attach to your issue on GitHub. You need to use Java 17+ and Maven 3+.
+
+Please run the following commands to make sure you have the sample working as expected:
+
+```shell
+$>unzip spring-batch-mcve.zip && cd spring-batch-mcve
+$>mvn package exec:java -Dexec.mainClass=org.springframework.batch.MyBatchJobConfiguration
+```
+
+You should see something like the following output:
+
+```
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.configuration.annotation.BatchRegistrar - Finished Spring Batch infrastructure beans configuration in 5 ms.
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseFactory - Starting embedded database: url='jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=false', username='sa'
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.repository.support.JobRepositoryFactoryBean - No database type set, using meta data indicating: H2
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.configuration.annotation.BatchObservabilityBeanPostProcessor - No Micrometer observation registry found, defaulting to ObservationRegistry.NOOP
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.configuration.annotation.BatchObservabilityBeanPostProcessor - No Micrometer observation registry found, defaulting to ObservationRegistry.NOOP
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.launch.support.SimpleJobLauncher - No TaskExecutor has been set, defaulting to synchronous executor.
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.launch.support.SimpleJobLauncher - Job: [SimpleJob: [name=job]] launched with the following parameters: [{}]
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.job.SimpleStepHandler - Executing step: [step]
+hello world
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.step.AbstractStep - Step: [step] executed in 11ms
+[org.springframework.batch.MyBatchJobConfiguration.main()] INFO org.springframework.batch.core.launch.support.SimpleJobLauncher - Job: [SimpleJob: [name=job]] completed with the following parameters: [{}] and the following status: [COMPLETED] in 34ms
+COMPLETED
+```
+
+# Reporting a bug
+
+Once you have the minimal complete verifiable example running as expected, you can import it as a Maven project in your favourite IDE. Please make sure to:
+
+* Update the sample as needed to reproduce your issue. We have placed a few TODOs where we expect you to modify the code.
+* Add any dependency that is required to reproduce your issue.
+* Keep the bare minimum code that is required to reproduce your issue. This is very important! Please reduce as much noise as possible to let us focus on the code related to the issue.
+
+Once you manage to reproduce the issue, please clean up the `target` directory *before* creating the zip archive to upload. Here are the commands you can run to create the archive:
+
+```shell
+$>mvn clean
+$>zip -r spring-batch-mcve.zip spring-batch-mcve
+```
+
+:exclamation: Important note: The `mvn clean` command is very important here. Please **DO NOT** include the `target` directory with all dependencies in the archive! We appreciate your collaboration on this.
+
+Heads-up: If you think you can reproduce the issue with a JUnit test, that is awesome! The minimal example that we provide
+has a JUnit test that you can edit as needed to reproduce the issue. Moreover, the minimal example we provide uses an in-memory H2 database, but if your issue is related to a specific database, please do not hesitate to add a Docker based test using
+the [Testcontainers](https://www.testcontainers.org) library and the JDBC driver of your database. You can find several examples in the test suite of Spring Batch [here](https://github.com/spring-projects/spring-batch/blob/main/spring-batch-core/src/test/java/org/springframework/batch/core/test/repository/MySQLJobRepositoryIntegrationTests.java).
+
+# Final thoughts
+
+More importantly, put yourself in the shoes of the project maintainer who is in charge of analysing and trying to reproduce your issue. Before uploading your minimal example, ask yourself: "How fast the Spring Batch team can understand and reproduce my issue?"
+
+Once we download your zip archive from the corresponding issue on GitHub, we expect to be two commands away from seeing a stack trace or the described abnormal behaviour:
+
+```shell
+$>unzip spring-batch-mcve.zip && cd spring-batch-mcve
+$>mvn package exec:java -Dexec.mainClass=org.springframework.batch.MyBatchJobConfiguration
+```
+
+Finally, please remember that those instructions are guidelines and not hard requirements. Be pragmatic! For example, if you already have a GitHub repository with the minimal example, there is no need to zip it and attach it to the issue, you would just need to add a link to it in your issue. If you think the issue is really obvious and does not require a minimal example, there is no need to create such an example, just go ahead and create the issue on GitHub by following the [Issue Template](https://github.com/spring-projects/spring-batch/blob/main/.github/ISSUE_TEMPLATE/bug_report.md).
+
+We appreciate your collaboration and we would like to thank you upfront for your time and effort!