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: ISSUE_REPORTING.md
+54-10
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,15 @@
1
-
# Issue reporting Guidelines
1
+
# Issue Reporting Guidelines
2
2
3
3
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.
4
4
5
-
Our goal is to have a streamlined process for evaluating issues so bugs get fixed more quickly!
5
+
Our goal is to have a streamlined process for evaluating issues so that bugs get fixed more quickly!
6
6
7
-
# Downloading the minimal complete verifiable example
7
+
# How do I report a bug?
8
8
9
-
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+.
9
+
## 1. Download the template of a minimal complete verifiable example
10
+
11
+
We provide a template of 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).
12
+
This example uses an in-memory H2 database and 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+.
10
13
11
14
Please run the following commands to make sure you have the sample working as expected:
12
15
@@ -32,13 +35,15 @@ hello world
32
35
COMPLETED
33
36
```
34
37
35
-
#Reporting a bug
38
+
## 2. Edit the example as needed
36
39
37
40
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:
38
41
39
42
* Update the sample as needed to reproduce your issue. We have placed a few TODOs where we expect you to modify the code.
40
-
* Add any dependency that is required to reproduce your issue.
41
-
* 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.
43
+
* Add any dependency that is required to reproduce your issue in the `pom.xml` file.
44
+
* Keep only the 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.
45
+
46
+
## 3. Package the example and attach it to your issue
42
47
43
48
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:
: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.
51
56
52
-
Heads-up: If you think you can reproduce the issue with a JUnit test, that is awesome! The minimal example that we provide
53
-
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
54
-
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).
57
+
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.
58
+
59
+
# What if I use another database than H2?
60
+
61
+
If your issue is related to a specific database, please start with the same example as in the previous section and add a Docker-based test using the [Testcontainers](https://www.testcontainers.org) library and the JDBC driver of your database.
62
+
63
+
For example, if you use PostgreSQL, you might add the following dependencies to the `pom.xml` file:
64
+
65
+
```xml
66
+
<!-- PostgreSQL JDBC driver -->
67
+
<dependency>
68
+
<groupId>org.postgresql</groupId>
69
+
<artifactId>postgresql</artifactId>
70
+
<version>42.6.0</version> <!-- update the version if needed -->
71
+
</dependency>
72
+
73
+
<!-- Testcontainers module for PostgreSQL -->
74
+
<dependency>
75
+
<groupId>org.testcontainers</groupId>
76
+
<artifactId>postgresql</artifactId>
77
+
<version>1.17.6</version> <!-- update the version if needed -->
78
+
<scope>test</scope>
79
+
</dependency>
80
+
```
81
+
82
+
Also, remember to remove the H2 dependency as well, to keep the example as minimal as possible even in terms of dependencies.
83
+
84
+
You can find several examples of Docker-based tests in the [test suite of Spring Batch](https://github.com/spring-projects/spring-batch/blob/main/spring-batch-core/src/test/java/org/springframework/batch/core/test/repository), and a specific example for PostgreSQL [here](https://github.com/spring-projects/spring-batch/blob/main/spring-batch-core/src/test/java/org/springframework/batch/core/test/repository/PostgreSQLJobRepositoryIntegrationTests.java).
85
+
86
+
# What if I use Spring Boot?
87
+
88
+
If you use Spring Boot, the best way to create a minimal example is to generate a project on [https://start.spring.io](https://start.spring.io).
89
+
90
+
Here is a quick link to generate a Maven-based Spring Boot application with Spring Batch and H2: [Sample project](https://start.spring.io/#!type=maven-project&language=java&platformVersion=3.0.4&packaging=jar&jvmVersion=17&groupId=com.example&artifactId=demo&name=demo&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.demo&dependencies=batch,h2).
91
+
92
+
You can also generate a project on the command line, for example with `cURL`:
0 commit comments