Improve documentation coverage for Spring Batch #19211

Buzzardo · 2019-12-02T19:04:08Z

At Michael Minella's suggestion and with his input, I extended the Batch section of the How-to page to include more detail.

snicoll

Thanks for the PR.

They are a number of TODOs in this PR and I am confused as whether you're expecting us to answer those or if you're waiting for some input of the Spring Batch team.

snicoll · 2019-12-09T10:37:15Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc


-NOTE: By default, batch applications require a `DataSource` to store job details.
+* <<howto-spring-batch-specifying-a-data-source>>


We usually don't list sections like that. Our toc on the left hand side offers a list of sub-sections anyway so I think this is redundant (and likely to be outdated if we forget to update the list).

It's regarded as a best practice (part of information mapping) in the technical writing community. However, I removed it, because I have no idea how it works with the ToC being constantly present. Do readers refer to the ToC as they read? (I don't, but I'm not everyone.) I wish I had data around that, to have something other than intuition on which to base this kind of decision. Anyway, I removed it.

snicoll · 2019-12-09T10:42:28Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

-
-[[howto-execute-spring-batch-jobs-on-startup]]
-=== Execute Spring Batch Jobs on Startup
+[[howto-run-spring-batch-jobs-on-startup]]


If the anchor is changed, I'd rather harmonize it to the same prefix as you've done for everything else.

snicoll · 2019-12-09T10:44:51Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

+They work a bit differently. However, for the most part, the differences do not cause
+trouble. However, they parse command line arguments differently, which can cause trouble,
+as described in the next section.
+// TODO What are the other differences between the two?


Is that something we're supposed to handle?

The other difference is that the CommandLineJobRunner from batch can accept options like -next, -stop, -restart, etc while the one from boot does not.

I left out that detail, since I didn't think it would help a user of Spring Boot.

snicoll · 2019-12-09T10:45:52Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

+
+==== Passing Command-line Arguments
+
+If you run Spring Batch with Spring Boot, Spring Boot strips the first `-` character (a


This section should use one sentence per line as the rest of the doc please.

I made that change.

snicoll · 2019-12-09T10:47:34Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

+In the second example, Spring Boot passes the parameter to Spring Batch as
+`-jobParameters="someParameter"`, and "someParameter" does not become the name of the
+`Job`.
+// TODO In that case, what is the name of the job?


I must admit I am bit confused by the current phrasing. Shouldn't we rephrase it around stating that Spring Boot uses -- as a signal for application arguments and that this clash with the way Spring Batch core works?

For this TODO, it is not the name of the job that is relevant, it is rather the job instance identity. When there is "-" in front of a parameter, the parameter is considered as non-identifying and will not contribute to the identity of the job instance. So the sentence could be re-phrased to something like:

In the second example, Spring Boot passes the parameter to Spring Batch as
-someParameter="someValue", and "someParameter" will be considered as a non-identifying job parameter.

I wrote a paragraph at the top of this section to address Stéphane's concern. Then I made the change Mahmoud suggested.

Buzzardo · 2019-12-10T16:00:15Z

I've asked Mahmoud Ben Hassine (benas here on Github) to review the TODOs. Once that is done, I'll fix it up. Unfortunately, I can't add him as a reviewer.

snicoll · 2019-12-11T07:31:10Z

Waiting for input from @benas then...

fmbenhassine · 2019-12-12T08:56:10Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

+https://docs.spring.io/spring-batch/trunk/reference/html/configureJob.html#configuringJobRepository[Configuring
+a Job Repository]
+// TODO Is it best practice to use a database (rather than the default Map object) for
+// the Job Repository, even when Spring Boot isn't present?


yes, the map based job repository is only intended for testing (as mentioned in its javadoc).

I dropped most of this, because it doesn't apply under Spring Boot. (I originally wrote this document as a stand-alone document.)

fmbenhassine · 2019-12-12T09:20:52Z

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

+example:
+
+[source]
+jobParameters="someParameter"


This is confusing, I would use someParameter="someValue" instead.

Good plan. I kept jobParameters when it's clear we're talking about exactly that argument.

At Michael Minella's suggestion and with his input, I extended the Batch section of the How-to page to include more detail.

Stéphane Nicoll and Mahmoud Ben Hassine had comments on my changes. I have accounted for their input. Thanks, Stéphane and Mahmoud.

See gh-19211

philwebb added this to the 2.2.x milestone Dec 2, 2019

philwebb added the type: documentation A documentation update label Dec 2, 2019

snicoll changed the title ~~More detail for Batch within Boot~~ Improve documentation coverage for Spring Batch Dec 7, 2019

snicoll reviewed Dec 9, 2019

View reviewed changes

snicoll added the status: waiting-for-feedback We need additional information before we can continue label Dec 9, 2019

spring-projects-issues added status: feedback-provided Feedback has been provided and removed status: waiting-for-feedback We need additional information before we can continue labels Dec 10, 2019

snicoll added status: waiting-for-feedback We need additional information before we can continue and removed status: feedback-provided Feedback has been provided labels Dec 11, 2019

fmbenhassine reviewed Dec 12, 2019

View reviewed changes

Jay Bryant added 2 commits December 12, 2019 12:01

More detail for Batch within Boot

d1893cf

At Michael Minella's suggestion and with his input, I extended the Batch section of the How-to page to include more detail.

Accounted for feedback

4290a67

Stéphane Nicoll and Mahmoud Ben Hassine had comments on my changes. I have accounted for their input. Thanks, Stéphane and Mahmoud.

snicoll removed the status: waiting-for-feedback We need additional information before we can continue label Dec 23, 2019

snicoll self-assigned this Dec 23, 2019

snicoll pushed a commit that referenced this pull request Dec 23, 2019

Improve Spring Batch coverage in reference documentation

6bd9b2e

See gh-19211

snicoll added a commit that referenced this pull request Dec 23, 2019

Polish "Improve Spring Batch coverage in reference documentation"

5f987a6

See gh-19211

snicoll modified the milestones: 2.2.x, 2.2.3 Dec 23, 2019

snicoll mentioned this pull request Dec 23, 2019

Improve documentation coverage for Spring Batch #19439

Closed

snicoll closed this in 4fb0a2b Dec 23, 2019

snicoll added a commit that referenced this pull request Dec 23, 2019

Polish Spring Batch how-to guides

930a0ef

See gh-19211

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation coverage for Spring Batch #19211

Improve documentation coverage for Spring Batch #19211

Buzzardo commented Dec 2, 2019 •

edited

snicoll left a comment

snicoll Dec 9, 2019

Buzzardo Dec 12, 2019

snicoll Dec 9, 2019

Buzzardo Dec 12, 2019

snicoll Dec 9, 2019

fmbenhassine Dec 12, 2019 •

edited

Buzzardo Dec 12, 2019

snicoll Dec 9, 2019

Buzzardo Dec 12, 2019

snicoll Dec 9, 2019 •

edited

fmbenhassine Dec 12, 2019 •

edited

Buzzardo Dec 12, 2019 •

edited

Buzzardo commented Dec 10, 2019

snicoll commented Dec 11, 2019

fmbenhassine Dec 12, 2019

Buzzardo Dec 12, 2019

fmbenhassine Dec 12, 2019

Buzzardo Dec 12, 2019


		NOTE: By default, batch applications require a `DataSource` to store job details.
		* <<howto-spring-batch-specifying-a-data-source>>


		==== Passing Command-line Arguments

		If you run Spring Batch with Spring Boot, Spring Boot strips the first `-` character (a

Improve documentation coverage for Spring Batch #19211

Improve documentation coverage for Spring Batch #19211

Conversation

Buzzardo commented Dec 2, 2019 • edited

snicoll left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fmbenhassine Dec 12, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snicoll Dec 9, 2019 • edited

Choose a reason for hiding this comment

fmbenhassine Dec 12, 2019 • edited

Choose a reason for hiding this comment

Buzzardo Dec 12, 2019 • edited

Choose a reason for hiding this comment

Buzzardo commented Dec 10, 2019

snicoll commented Dec 11, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Buzzardo commented Dec 2, 2019 •

edited

fmbenhassine Dec 12, 2019 •

edited

snicoll Dec 9, 2019 •

edited

fmbenhassine Dec 12, 2019 •

edited

Buzzardo Dec 12, 2019 •

edited