Jakarta Batch 2.0

[scottkurz]

NOTE: At this point it appears that we still need the CDI (Wave 3) and JTA (Wave 4, like Batch) dependencies to be staged

Specification PR template

When creating a specification project release review, create PRs with the content defined as follows.

Include the following in the PR:

• A directory in the form wombat/x.y where x.y is the release major.minor version, and the directory contains the following.
• Specification PDF in the form of wombat-spec-x.y.pdf
• Specification HTML in the form of wombat-spec-x.y.html
• A specification page named _index.md following the template at:
  https://github.com/jakartaee/specification-committee/blob/master/spec_page_template.md
• (N/A) For a Progress Review, that sufficient progress has been made on a Compatible Implementation and TCK, to ensure that the spec is implementable and testable.
• For a Release Review, a summary that a Compatible Implementation is complete, passes the TCK, and that the TCK includes sufficient coverage of the specification.
  The TCK users guide MUST include the instructions to run the compatible implementations used to validate the release.
  Instructions MAY be by reference.
• The URL of the OSSRH staging repository for the api, javadoc:
  https://jakarta.oss.sonatype.org/content/groups/staging/jakarta/batch/jakarta.batch-api/2.0.0/
• The URL of the staging directory on downloads.eclipse.org for the proposed EFTL TCK binary:
  https://download.eclipse.org/jakartabatch/tck/eftl/jakarta.batch.official.tck-2.0.0.zip
• The URL of the compatibility certification request issue:
  Certification Request for jbatch v2.0.0-M7 + jakarta batch api v2.0.0 batch#110
• Specification JavaDoc in the wombat/x.y/apidocs directory.

===================================================================================

[netlify]

Deploy preview for jakartaee-specifications ready!

Built with commit ebbe3c0

https://deploy-preview-238--jakartaee-specifications.netlify.app

[kazumura]

Spec Review Checklist

1. Spec PR

• PR uses template
• Directory of form {spec}/x.y
• PDF of form {spec}-spec-x.y.pdf ("-spec" preferred but not required)
• HTML of form {spec}-spec-x.y.html ("-spec" preferred but not required)
• Index page {spec}/x.y/_index.md following template
• Index page {spec}/_index.md following template
• No other files (e.g., no jakarta_ee_logo_schooner_color_stacked_default.png)
• Staging repository link of the form https://jakarta.oss.sonatype.org/content/repositories/staging/jakarta/{spec}/jakarta.{spec}-api/x.y.z/
• EFTL TCK link of the form http://download.eclipse.org/.../+.zip
• Compatibility certification link of the form https://github.com/eclipse-ee4j/{project}/#{issue}
• (Optional) Second PR for just apidocs

2. _index.md

• Link to spec pdf
• Link to spec html
• Link to apidocs
• Link to final TCK download zip file of the form https://download.eclipse.org/jakartaee/{spec}/x.y/*{spec}-tck-x.y.z.zip
• Link to API jar file of the form https://search.maven.org/artifact/jakarta.{spec}/jakarta.{spec}-api/x.y.z/jar
• Name of and link to at least one Compatible Implementation

3. javadocs

• Footer contains Eclipse copyright and link to license
• ESFL license is included, usually as doc-files/speclicense.html
• no META-INF directory in PR
• javadocs-jar artifact matches apidocs (optional for this release)

4. Spec PDF

• Correct spec title
• Version number of the form x.y, not x.y.z
• Correct Eclipse copyright line
• No DRAFT or SNAPSHOT
• Correct Logo

5. Spec HTML

• Same as PDF

6. TCK zip file

• README file (optional for this release)
• EFTL license file, preferably named LICENSE.md
• User's Guide (or equivalent documentation)
• How to test the Compatible Implementation(s) listed in _index.md above with the TCK (may be in UG)

7. TCK User's Guide (or equivalent documentation)

• Software requirements listed
• Installation and configuration described
• How to run tests
• Where to file challenges

8. Compatibility certification request

• Request follows template
• SHA-256 fingerprint matches staged TCK zip file
• Request issue has certification label.

9. TCK results summary

• Page is hosted by Compatible Implementation project
• Includes all information from certification request
• Summary includes number of tests passed, failed, errors
• SHA-256 fingerprint matches staged TCK zip file on cert request

10. Update Jakarta EE API jar

• Update the Jakarta EE API jar by submitting a PR to the jakartaee-api project that updates the version number of your API jar file.

[scottkurz]

@kazumura, I think this is ready to continue reviewing (thank you for the review so far).
I do have a PR on the jakartaee-api project here: jakartaee/jakartaee-api#71

Note on my compatible impl for certification request

jakartaee/batch#110

I know this isn't the first situation like this, but there's a bit of a circular dependency here: the final release of the 'jbatch' impl we use to certify has a dependency on the spec/API, but the certifying impl is needed to finalize the spec/API.

I thought the most useful thing to do at this point was to write up the certification issue as if this were the final 2.0.0 release of the 'jbatch' implementation, so you'll see the 2.0.0 version mentioned in the certification issue.

I would expect to come back and update the certification issue when the specification is complete, at which point I can perform the final release of the 2.0.0 'jbatch' implementation.

However, another alternative would be to simply use a "Release Candidate" type of release of 'jbatch' as the certifying implementation. I could rework the jakartaee/batch#110 issue if that is preferred. One downside of that is that I would have to use a pre-final version of the 'jbatch' dependency on JTA.

@kwsutter, please let me know if you have any thoughts here, and if the specification process has any more detailed guidance I should be following for a case like this. If I'm overthinking this that's fine too. I think there's enough transparency captured in the combination of the batch-api issue and the impl issue.

Thank you!

[kwsutter]

@kwsutter, please let me know if you have any thoughts here, and if the specification process has any more detailed guidance I should be following for a case like this. If I'm overthinking this that's fine too. I think there's enough transparency captured in the combination of the batch-api issue and the impl issue.

You could go the RC route, if you wish. Just so that it sticks around in a public location (ie. maven or github or downloads). Other components are using "Alpha" or "Milestone" drivers in the same light. Whatever works for your testing and certification. Thanks.

[kazumura]

LGTM. Thanks, @scottkurz

[kwsutter]

@scottkurz The pdf version of the Spec doesn't seem to be readable. The html is rendered just fine, but I can't read the pdf with any type of viewer.

[kazumura]

@scottkurz The pdf version of the Spec doesn't seem to be readable. The html is rendered just fine, but I can't read the pdf with any type of viewer.

The pdf file committed at Jul 26 was OK, but the pdf file committed at Jul 31 seem to be html.

[scottkurz]

@kazumura , @kwsutter

I renamed to jakarta-batch-spec-2.0.pdf/html and fixed the broken PDF. Within the spec document I fixed a bunch of broken links to sections within the doc.

I re-staged the API jar as well since it's easier for me to keep the spec+API both updated together in the Maven staging repo. So I copied the newly-generated Javadoc, which should be equivalent to the old, into this PR so it will match what gets released to Maven. Then I re-ran the TCK too against the new API jar.

Thanks for your review.

[kwsutter]

Thanks, @scottkurz. Since Scott updated several items in this PR, I think @kazumura needs to do another final re-review before it's ready for ballot. I just requested another review from Kenji. I won't remove any of the labels since I think this will be done in short order before sending out the ballot. Thanks!

[kwsutter]

Both the PDF and HTML are readable now. Thanks, @scottkurz!

[kazumura]

LGTM

Question on the zip name

[jeanouii]

See comment on the zip file name.
Not sure it's a blocker

[jeanouii]

Why is there an "official" in the zip name?

[kazumura]

In the Spec. committee meeting at Aug 12, we discussed about the form of zip file name,
and we agreed that the folder path is required, the file name pattern is preferred.

[kazumura]

• The specification committee mentor adds this final checklist to the main PR.
• The specification committee member adds the approved label to the PRs, and sends out the Ballot Summary per this template to the public Jakarta EE Specification Committee email list
• The specification committee mentor merges the specification (and apidocs) PRs, ensuring the "date:" field in the _index.md file has an appropriate value to allow publishing.
• The specification committee mentor calculates the staged EFTL TCK signature and promotes it to the committee download area
  using the https://ci.eclipse.org/jakartaee-spec-committee/job/promote-release/ job.
• The specification project member who created the api staging release promotes the specification api jars to maven central. An example release job script can be found here https://wiki.eclipse.org/MavenReleaseScript.
• The specification committee mentor updates the specification page with the ballot results.
  This list goes on the committed spec index page.
• The specification project team should go through the merged spec website page to verify all the links are valid.
• The specification project team should approve the compatibility request.
• The compatible implementation project/vendor MUST send an email to tck@eclipse.org for approval of the compatible implementation for trademark usage.
• The specification project team should merge any final release branch as appropriate for the branch management for the project.