Concurrency 3.0 release review

[njr-11]

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 jakarta-wombat-spec-x.y.pdf
• Specification HTML in the form of jakarta-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
• 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.
  N/A
• 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.
  • Updated release record
  • Generated IP Log
    https://dev.eclipse.org/ipzilla/show_bug.cgi?id=24077
  • Email to PMC
  • Start release review by emailing EMO
• The URL of the OSSRH staging repository for the api, javadoc:
  https://jakarta.oss.sonatype.org/content/groups/staging/jakarta/enterprise/concurrent/jakarta.enterprise.concurrent-api/3.0.0/
• The URL of the staging directory on downloads.eclipse.org for the proposed EFTL TCK binary:
  staging: https://download.eclipse.org/ee4j/cu/jakartaee10/staged/eftl/
  promoted: https://download.eclipse.org/ee4j/cu/jakartaee10/promoted/eftl
• The URL of the compatibility certification request issue:
  Compatibility certification request for Open Liberty 22.0.0.5-beta for Jakarta Concurrency 3.0 (of Jakarta EE 10) concurrency#175
• Specification JavaDoc in the wombat/x.y/apidocs directory.
  If desired, an optional second PR can be created to contain just the JavaDoc in the apidocs directory.

Note: If any item does not apply, check it and mark N/A below it.

[netlify]

✅ Deploy Preview for jakartaee-specifications ready!

Name	Link
🔨 Latest commit	61bc406
🔍 Latest deploy log	https://app.netlify.com/sites/jakartaee-specifications/deploys/627a71ca3644b900094a48c3
😎 Deploy Preview	https://deploy-preview-449--jakartaee-specifications.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[edbratt]

@m0mus and I will be your Spec. review mentors. We will be following this check-list to prepare the specification and associated material. Once these items are completed, we will start the release ballot.

Spec Review Checklist

1. Spec PR

• PR uses template
• Directory of form {spec}/x.y
• PDF of form jakarta-{spec}-spec-x.y.pdf ("-spec" preferred but not required)
• HTML of form jakarta-{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) -- Images for HTML Spec. are included in separate images folder. (This is was agreed as a workaround to prevent large files created with fully embedded content.)
• 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 -- Temporary links are provided currently (4/27/22) -- final links to be updated after ballot success.
• Compatibility certification link of the form https://github.com/eclipse-ee4j/{project}/#{issue}
• (Optional) Second PR for just apidocs

2. _index.md

• Link to project release plan of the form https://projects.eclipse.org/projects/ee4j.{spec}/releases/x.y/plan
• 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 (The folder path is required, the file name pattern is preferred.) -- Temporary links are provided currently (4/27/22) -- final links to be updated after ballot success.
• 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
• Review summary statement to ensure it has been updated to reflect the work accomplished and does not contain proposal statements as might be found in Plan Review statement.

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. If a Release Review is required, the specification project team contacts the EMO to initiate the review by sending an email to emo@eclipse.org.
    (A Release Review is not required if the current release is a Service Release based on a previously successful Major or Minor
    release as indicated by a release record on the project's Releases page, e.g., the Jakarta Servlet releases page.)

    • An issue will be created by the EMO to track the release review.
    • The specification project team requests approval for the release from the PMC by sending an email to ee4j-pmc@eclipse.org.
    • The specification project team then delivers an IP Log to the IP Team for their review as described in https://www.eclipse.org/projects/handbook/#pmi-commands-iplog.

11. 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.

[edbratt]

The TCK must be licensed under the EFTL. For distribution via Maven, the TCK may be dual licensed: EFTL + EPL. Please revise the tom-level license docs and discard the EPL + GPL v2 license docs. Source-code license headers need not be updated.

I was unable to find the TCK Users Guide. This contains details about compatibility requirements. Please provide a pointer to this doc. or add it.

I will need to get clarification from the Spec. committee about the final distribution of the TCK materials. Current check-list requirement is that we provide the TCK as a complete bundle .zip file that is linked to the controlled Specifications download folder. For CU 3.0, this would be: download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip -- You can use the CU 2.0 archive to review the contents if that is helpful. Also please review the Mentor Checklist items 6, 7, and 8 for additional details.

I do see that there is a docs folder in the Maven source archive. This only includes the license file. Lacking further documentation, I would recommend this release use the previously created cu 2.0 TCK zip as the proposed list of contents -- if anything is to be discarded, we can explicitly decide to remove it.

The Java doc link to the Spec. License HTML file yields 404 in the Netlify preview. Please correct if needed.

In general, TCK Result links are not needed on the Specification info. page _index.md. That is only needed in the CCR itself. The CCR is included in the PR and that has been sufficient. Please remove these links.

[edbratt]

Rather than remove the plan I'd recommend either changing this to a list of accomplishments (and move it above the set of release pointers) or, you can refer readers to the Release Record link. If the latter, I would recommend you update the Release Record to state the list of accomplishments/changes. It might be helpful to summarize why this is a major release and provide references to any potential issues that would impact users who intend to upgrade. (Either here, or in the Release Record if you want to just refer readers to that.)

[njr-11]

Sorry about that. I had removed the Plan section because it was absent in the 2.0 release review which I was using as a guide, but now I realize it was a bad idea to copy from that because 2.0 didn't actually have any new function and was just the jakarta package rename.

To correct this, I'm following your first option and restoring the Plan section with a list of new features included just prior to the release information.

[edbratt]

TCK results are not necessary. Please remove the TCK result links. The CCR issue reference in the PR is sufficient.

[njr-11]

I'm removing these links. Thanks for pointing it out.

[edbratt]

This should be a pointer to the PMI plan (you are welcome to keep this link, but the PMI link is what is asked for in the checklist): https://projects.eclipse.org/projects/ee4j.cu/releases/3.0/plan

[njr-11]

Adding the link that you mentioned, but without removing either of the other links because it is unclear to me which was unnecessary and the 2.0 release review appears to have them both.

[njr-11]

I was unable to find the TCK Users Guide. This contains details about compatibility requirements. Please provide a pointer to this doc. or add it.

I added added a link to it under the TCK section. Let me know if there is any specific detail that must be added to it.

• TCK User's Guide

[edbratt]

I was unable to find the TCK Users Guide. This contains details about compatibility requirements. Please provide a pointer to this doc. or add it.

I added added a link to it under the TCK section. Let me know if there is any specific detail that must be added to it.

* [TCK User's Guide](https://github.com/eclipse-ee4j/concurrency-api/tree/master/tck)

The TCK User Guide (hopefully as final production artifact -- e.g. .html or .pdf) should be included in the TCK. This is part of the 'contract' that a vendor must follow when they are making a certification claim. If you look at the previous TCK version (Jakarta Concurrency 2.0.1 TCK), you can find this in the .zip file under the 'docs' folder. The readme.md file you refer to above is (at least to my eye) more akin to the release notes of the previous TCK.

In the previous version there was a list of associated rules for achieving compatibility (see Section 2.2.2 of the Concurrency 2.0.1 TCK User Guide). Has the concurrency team determined these are to be discarded? While these don't appear to require anything beyond the standard rules, I would be surprised if the proposal was to drop these. But, maybe I'm to be surprised.

The user-guide must include how to file test challenges. See the TCK Process Guide for what must be included (along with recommended other information). Prior to this release the User Guide for Concurrency was generated from JBake content -- the source came from this folder in the Jakarta EE Platform TCK project. You can see the final output in the previous TCK zip files, in the docs folder.

[njr-11]

In the previous version there was a list of associated rules for achieving compatibility (see Section 2.2.2 of the Concurrency 2.0.1 TCK User Guide). Has the concurrency team determined these are to be discarded? While these don't appear to require anything beyond the standard rules, I would be surprised if the proposal was to drop these. But, maybe I'm to be surprised.

I don't think anyone was aware of that section, or that whole document for that matter. I'll look into getting the rules copied over, and post EE10 it can be decided if other parts of that document should be included as well.

I had already opened a pull to get the information on where to file challenges included, so this can be added to that pull. It's unfortunate that this document will need to put inside of the TCK because that will mean needing to rebuild the TCK binary which invalidates the test results that we were supposed to be publishing tomorrow. Is that truly a requirement for the User Guide document to exist inside of the TCK binary?

[edbratt]

Is that truly a requirement for the User Guide document to exist inside of the TCK binary?

It is, as the TCK content is currently described. We will discuss at the Spec. committee but I can't predict when a resolution will be provided.

[njr-11]

@edbratt I added commit 1d520db to delete the unused contents of the images folder and comply with the "No other files (e.g., no jakarta_ee_logo_schooner_color_stacked_default.png)" requirement. You should be able to check off that box now.

[edbratt]

In the Spec. committee today, the notion of different artifacts for the different portions of the TCK was discussed. The conclusion was that, for EE 10, we will only allow for a single TCK archive -- this archive must contain the TCK runtime and all associated documentation and that is what must be used for any final certification. There is still discussion on this point but the best advice I can provide at this time is to model the TCK archive contents, using the previous release TCK. If you wish to deliver that same archive via Maven Central, you can simply change the name from .zip to .jar. I recognize the inconvenience of this and can only say that I'll work to modify this decision for a future release, but for now, please plan to deliver a TCK ZIP file that contains the runtime TCK; all necessary test artifacts; The read-me/user-guide; and any additional material that is needed to confirm compatibility.

Scott Stark suggested that he would provide some material that describes how the CDI project bundles these artifacts suitably. Perhaps you can follow that recipe.

[edbratt]

@njr-11 any update on progress with this? I'm still not seeing any TCK results associated with the CCR. Are the finalization issues for this Spec. related to details of the Spec., or with the finalization process? I probably can help with the process issues -- if that's what is hanging you up.

[njr-11]

@njr-11 any update on progress with this? I'm still not seeing any TCK results associated with the CCR. Are the finalization issues for this Spec. related to details of the Spec., or with the finalization process? I probably can help with the process issues -- if that's what is hanging you up.

We are opting to wait on officially reporting any TCK results until we have the TCK validly packaged. Thank you for the offer to help on process issues - @smillidge has taken over that aspect and can let you know where that is currently at and if further help is needed. The only other issue holding up the TCK at this point is that we were asked by Scott to bring over more of the documentation from the old TCK. @KyleAure is working on getting that part done. After that we will attempt again to build a candidate final version of the TCK.

[smillidge]

Looks like Scott's PR works and we can now build a valid package. See https://ci.eclipse.org/cu/view/Build-Test/job/Concurrency%20TCK%20Master%20Build/31/artifact/tck-dist/target/concurrency-tck-3.0.0-dist.zip

[edbratt]

The TCK ZIP looks good now.

As it stands now, I can check off all the boxes in that Mentor Checklist under 6 and 7 once the TCK is posted to a download folder.

So, now the team just needs to complete the staging of all the proposed final artifacts -- my checklist would include:

• Complete the TCK release to a download location -- Some groups use their own download folder. Others use the jakarta ee TCK folder. Personally, l'd recommend you use your own project folder. Don't forget you need an EFTL licensed TCK and a project license licensed TCK. they only differ by the LICENSE file in the top directory. Reach out to the TCK Project mailing list if you decide to put it into the project TCK download folder. Information about Eclipse Project downloads folders starts here. (here too)
• Update and complete test results and the Open Liberty CCR.

Update the PR to let me know it's ready for the actual final review and I should be able to check everything off and start the ballot.

[njr-11]

@edbratt this is ready for your review again. All of the checkboxes in the issue description are checked except for "Email to PMC" and "Start release review by emailing EMO".

[edbratt]

Contents looks good now. Thank you for the updates.

I did notice that the TCK JAR does not contain test source-code. This is not strictly a requirement so I won't hold this up further but please create a GitHub release or tag so that the test sources are readily obtainable. If you are also pushing artifacts to Maven, probably you are already generating a source jar. (I guess the 3.0.0 tag will suffice for this)

I also noticed that the test counts seem to vary. The CCR TCK page indicates 160 tests. Section 6.1 of the TCK Ref. guide says 164 tests, and the test results that are included later (section 9.1) shows 162 tests. This inconsistency isn't a show-stopper but if you do update it, consider ideas for refreshing these easily. It may be most expedient to to bubble this up to a read-me or other top-level document since this can frequently change right up to the release. (the sample output can be left alone with caveat text and the section 6.1 text might just refer to the TCK readme). If you do a respin for this, consider dropping a source JAR into the TCK as well.

Strictly speaking the TCK download links in _index.md should be pointing to files that don't exist yet (the target files will be uploaded after the ballot is successful).
The link targets should be as follows:

• https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip
• https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip.sha256
• https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip.sig

(with link text as it was on the 2.0 release.)

It would avoid some ballot commentary if you could update these links prior to the final merge. I could also do that for you with your permission.

[edbratt]

For the PMC release review, just send an e-mail to ee4j-pmc@eclipse.org, Request a release review for 3.0 and point to the 3.0 release record: https://projects.eclipse.org/projects/ee4j.cu/releases/3.0. The PMC is pretty responsive so this should be quick.
This is the issue the EMO is using to track this progress.

[njr-11]

@edbratt - thanks for the comments. For all of the optional ones, I opened jakartaee/concurrency#217 against the spec project to address in a future release. It's too close to the cutoff for EE 10 and I cannot justify risking exclusion from EE 10 for anything that isn't required.

The following comment, which as I understand is the only one required, I'm addressing with commit e9d00b3) to this pull. I did not list a .sig file separately because the signature test and all the files for it are part of the main TCK zip now, not a separate artifact.

Strictly speaking the TCK download links in _index.md should be pointing to files that don't exist yet (the target files will be uploaded after the ballot is successful). The link targets should be as follows:

* https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip

* https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip.sha256

* https://download.eclipse.org/jakartaee/concurrency/3.0/jakarta-concurrency-tck-3.0.0.zip.sig

(with link text as it was on the 2.0 release.)

As I understand from your other comment, you are asking me to initiate the PMC release review, so I'll get that done right away.

[njr-11]

@edbratt - The assignee to the EMO issue
https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/193
is asking for us to initiate the ballot. Can you do that now? The PMC Release Review was given a +1 by Ivar, but I don't know if additional votes are needed on that or if that is sufficient to proceed.

[edbratt]

With PMC release request, the review checklist is complete and I can start this ballot. Thank you for attending to all these issues.

[edbratt]

Ballot has completed. Now, onto the final check list steps.

[edbratt]

• adds this final checklist to the main PR.
• 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
• 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. Manually editing the jenkins Build Information will help identify the build (ie. Mail 2.0 or CDI 3.0).
• merges the specification (and apidocs) PRs, ensuring the "date:" field in the _index.md file has an appropriate value to allow publishing.
• updates the specification page with the ballot results. This is normally done via a separate PR that should be reviewed, approved, and merged.
• notifies the EMO of the ballot results by email to emo@eclipse-foundation.org. Just forward the ballot summary note sent earlier to the public Spec Committee email list.
• Spec. committer team finalization issue

Please don't forget to submit a PR to update the Jakarta EE API JAR.