|[jakartaee-platform-dev] Fwd: [jakarta.ee-spec.committee] [External] : Re: TCK archive format? (Consider allowing JAR or ZIP)
Forwarding a copy of the discussion previous -- related to packaging and delivery of artifacts for publication through Sonatype Maven ... (Sorry, I don't know how to host these cross-group discussion since the membership lists is not synchronized.)
We agreed this morning to discuss potential proposals for revised TCK delivery archives that the Platform team might want to recommend to the Spec. committee in it's call Wed. next week. We created an item to discuss this at the next Platform committer meeting (Tuesday a week from today).
The forwarded message thread is the conversation that, for the most part took place late last year. We weren't facing the final specification ballot reviews at that time and we never made any recommendations.
My personal goal is that we adapt the process requirements to
allow users to pull the binary TCK from Maven Central such that
this allows for a final certification to be completed and the
results submitted without any need to acquire an additional
download from an alternate location (e.g. from
download.eclipse.org). Users may need to read and abide by textual
details that are in the ancillary TCK documents, but the run-time
test aspects can be completed in a valid way, without running the
tests in any 'special' way, using an officially sanctioned
artifact. As I understand the process, today's process
requirements doesn't make that possible. In fact, none of the TCKs
that previously came from the Jakarta EE TCK Project were
'officially' available from Maven Central. Other component
specifications may have provided artifacts via Maven Central, but
unless they are SHA-SUM identical to the TCK provided at
download.eclipse.org, that would not be a technically valid TCK.
(Even the TCKs that are provided under the Project License are not
considered acceptable for certification since the sanctioned TCK
archives have the EFTL license rather than the Project License).
I don't feel qualified to propose a layout for material that is to be delivered through Maven central. I will summarize the elements listed in the TCK Process here (from Jakarta EE TCK Process 1.2):
The Jakarta EE TCK Process asserts that TCKs must be hosted from download.eclipse.org.
Additionally -- this document requires a SHA-256 hash to identify
the TCK that was used to determine compatibility.
Some issues to consider
Finally, if it wasn't ever stated to teams, I'd recommend all teams that are refactoring their TCK out of the Jakarta EE Platform TCK project, review the contents of that specification's 9.1 version TCK and use that, at least, as a starting point for their refactored TCK for EE 10. If anyone has questions (e.g. "where did this user guide come from?", "what is an assertion list?", etc.), questions can be answered here, and also in the Jakarta EE Platform TCK mailing list jakartaee-tck-dev@xxxxxxxxxxx. Prior to EE 10, none of the TCKs from the Jakarta EE TCK Project had been delivered via Maven Central. No doubt, we'll have some translation/porting issues to contend with as we make this transition.
Anyone that has a proposed layout and/or publication to Maven
proposal, please feel free to make a recommendation or explain how
their project might provide a suitable archive.
|Re: [jakarta.ee-spec.committee] [External] : Re: TCK archive format? (Consider allowing JAR or ZIP)
|Fri, 11 Feb 2022 16:03:51 -0800
|Ed Bratt <ed.bratt@xxxxxxxxxx>
|Jakarta specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>
|Jakarta specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>, Mike Milinkovich <mike.milinkovich@xxxxxxxxxxxxxxxxxxxxxx>
The time has arrived for us to settle on the questions here. I believe we need to make some choices about what we'll allow for EE 10.
The simplest but not most convenient choice is to simply state that TCKs will be archived and distributed as .zip files just as they have been in previous releases. The more complex choice is approve changes that will allow the final/normative TCKs to be referenced directly from Maven.
In my perspective, the User Guide documentation that is included can be quite lengthy -- and is more involved than a Readme type document. As Scott Stark pointed out -- to properly understand a TCK, one must review the documentation and know the details of the runtime requirements, configurations, extended instructions, etc. before using them. Though forcing them to be delivered in the download doesn't ensure that the user documentation is read or understood.
If we are going to allow Maven publication, I believe the
following must be part of any recommendation we provide:
We /could/ agree that the TCK runtime is published separately from the documentation. Further that we publish the runtime as a separate archive (presumably a JAR)-- but to both Maven and to the Specifications download (using a SHA-SUM to verify the two are identical) -- and simply refer vendors (perhaps via short read-me) to the separate downloadable TCK documentation bundle. This creates some problems while solving others.
This is somewhat urgent since I need to provide guidance to the Concurrency Utilities team regarding what we will allow/not allow with their current release proposal.
I believe we have previously discussed and received assurance that dual-licensed TCKs (any artifact) are acceptable to Sonatype. So, these would require both the TCK license and the project license. Currently, the TCKs are produced under the project license while they are under development. When they are finalized, they are made available under the TCK license. I thought that we determined dual license was acceptable from the Working Group / Eclipse side but, if you are not sure, please do check if this is still allowable.
The certification process steps still require the Compatibility Certification Request with it's attestations. The Branding and Trademark processes is also still a requirement for those who choose those paths.
Subject to your assurance that this is an allowable delivery pattern, my goal with this discussion is to see if there is an opportunity for us to make the TCKs operate like any other Java element and can be built into the same developer delivery channel as other Java artifacts. I view this as a simplification and broadening of availability effort.
Emily and others, when a CCR is submitted, the submitter is required to include the SHA-256 hash of the TCK package that they used for their certification. Only finalized and approved TCKs and their corresponding SHA sums are acceptable. Therefore, only a single distribution is allowed -- under our current process.
Part of this discussion is to work out how to adjust our process, if we can find a proper solution that meets all procedural and mechanical requirements.
On 12/9/2021 5:59 AM, Mike Milinkovich wrote:
Beyond any technical considerations the licensing and patent IP flows in the JESP/EFSP are predicated on the use of the normative TCK binary made available under the TCK License. So there would be legal analysis required to enable this scenario.
On 2021-12-08 7:13 p.m., Scott Stark wrote:
I see what you are driving at, but this will definitely take some thinking about how to achieve. One could probably publish all of the relevant artifacts to a maven repo using qualifiers/naming conventions to cover user guide, exception list, etc.
On Dec 8, 2021 at 4:58:57 PM, Ed Bratt <ed.bratt@xxxxxxxxxx> wrote:
Maybe the problem is with how we are "packaging" the TCK content.
The TCK is the only Spec. artifact we create a SHA Sum for. The archive we use for the TCK includes the documentation which is generally not part of a typical Java binary JAR (i.e. at Maven Central, there's typically a Binary JAR, a Source JAR, a Java Doc JAR and maybe others -- but they're all separate).
We currently bundle all the TCK component elements into a single archive -- a ZIP archive. We treat that as a single deliverable. At the Spec. generation end, that makes production of that archive a multi-step process. Contrast that with the publication of the API, binary, and Java Doc JARs with the code-based resources can directly be published to, Maven central (or another repository service if the vendor liked). So, the normative code-based Spec. artifacts can be easily pulled into an Mvn script but the normative TCK elements cannot.
I'd like the TCKs to be accessible via maven because I think that improves the access flow for developer users. I understand that developers typically will need additional details to understand how to use these artifacts but, once they have that worked out -- I'd like to improve how these can be distributed more readily, using common build tools (I typically think mvn, but others also exist). I don't think using the TCK artifacts are all that much different from using a binary API jar file -- you have to know how to use the JAR before you pull it in.
In the context of the process we have today -- a binary (run-time) TCK JAR cannot be pushed to Maven central as a normative artifact because we track the zip bundle with the SHA SUM and Signature hash. To "properly" certify an implementation, even if we pushed the binary elements of the TCK to Maven, users would still need to pull down the normative copy, unpack and "install" those artifacts, then run/validate their implementation with that binary. (Or, just attest that is what they did. I'd assert that we don't want a process that promotes 'looking the other way.')
So, I thought, if perhaps we could just create a JAR file that had the same content as what is currently in the ZIP -- thinking that maybe we might simplify that process by one step -- but I'm now seeing that probably isn't going to 'just work.' So just changing the extension name from .zip to .jar won't cut it.
I want to make it possible for developers to pull normative TCK binaries down from Maven (or whatever their chosen repository happens to be). I want the artifacts that are pushed to the Jakarta EE Spec. download to exactly match what can be accessed from Maven -- or at least the run-time parts that are actually used at build-time.
Today, before the Spec. is finally approved, I can pre-test my implementation using the pre-final TCK .zip files. Once the Spec. is finalized, that zip is exactly copied to the Jakarta EE Specification Download folder and the SHA-SUM and Signature hash are generated (the SHA sum won't change because the binary is identical and the signature hash works correctly too). So, I don't need to re-run the TCK because it's unchanged (in any scenario where a change might have been needed, the SHA Sum would not be the same and I would need to re-verify the compatibility of my implementation -- even if the change was to a non-binary element of that archive.)
I was hoping we could figure this out for EE 10, but maybe it's just too late to consider making changes to allow for this that rapidly.
Does this make sense?
On 12/8/2021 11:36 AM, Scott Stark wrote:
There is no access to a user guide (required) and any example CI setup that is often included in a full TCK dist. Users certainly should have the ability to directly access the components directly via a repo, but I don't see how that can be the only mechanism when it comes to ratifying the associated spec. Am I missing the context in which you are asking about this?
On Dec 8, 2021 at 12:09:53 PM, Ed Bratt <ed.bratt@xxxxxxxxxx> wrote:
This seems to suggest that users should NOT have access directly to the normative TCK artifacts -- That they should pull the comprehensive archive, unpack and digest it, THEN, utilize the contents. Is that a fair re-state?
We include GAVs for the API jars and JavaDocs. Why would we want to enforce force additional overhead on the TCKs (both on construction of the archive and on consumption)? (Or, what it is about TCK usage that I'm minimizing.)
On 12/8/2021 8:02 AM, Scott Stark wrote:
For the final submission I still think there needs to be a single zip that is comprehensive. The use of jar artifacts in a repo facilitates the ability to easily integrate TCK testing into CI environments, but it is a bad starting point to running the TCKs. Only after you have gone through the full zip distribution and associated user guide/example do you start wanting the individual artifacts.
On Dec 8, 2021 at 9:58:16 AM, Ed Bratt <ed.bratt@xxxxxxxxxx> wrote:
As we move the TCK responsibilities to component projects and, as we
continue migrating away from the legacy TCK build tools, to MVN or other
build tooling, I wonder if we should hold on to the requirement that we
only accept .zip file bundles for normative TCK submissions.
Would the committee be interested in relaxing the formal requirements to
allow either <name>.zip OR <name>.jar? If we did this, projects would
not need to create multiple bundles and we could start to use Maven
Central or other types of distribution mechanisms more directly.
I believe all other requirements (SHA Sums, contents, etc.) can be
maintained just as directly with either file format.
I don't know that we could adopt this before the close of the year, but
... perhaps this is simple enough to take up without extensive discussion.
jakarta.ee-spec.committee mailing list
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee
_______________________________________________ jakarta.ee-spec.committee mailing list jakarta.ee-spec.committee@xxxxxxxxxxx To unsubscribe from this list, visit https://urldefense.com/v3/__https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee__;!!ACWV5N9M2RV99hQ!a7DQDPqHeJq3Q0JbFqLFGnY9MKejqQtnohN_jFIYScnrOBo80YCr4N58Bxi9VNM$
_______________________________________________ jakarta.ee-spec.committee mailing list jakarta.ee-spec.committee@xxxxxxxxxxx To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee--
Executive Director | Eclipse Foundation AISBL
This email has been checked for viruses by Avast antivirus software.
_______________________________________________ jakarta.ee-spec.committee mailing list jakarta.ee-spec.committee@xxxxxxxxxxx To unsubscribe from this list, visit https://urldefense.com/v3/__https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee__;!!ACWV5N9M2RV99hQ!fHraA8um0eKgNng_5TBlhok7ptQ-hZo0sO2H1FIv2Xg8a05iTGZzOJcdydYSpfc$
_______________________________________________ jakarta.ee-spec.committee mailing list jakarta.ee-spec.committee@xxxxxxxxxxx To unsubscribe from this list, visit https://urldefense.com/v3/__https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee__;!!ACWV5N9M2RV99hQ!YGPZOkbYZcXimcG6-E7MjUL-WNkbh0OKAcfF-RDF85SNaGxkTijadkXaN0BgpNU$
_______________________________________________ jakarta.ee-spec.committee mailing list jakarta.ee-spec.committee@xxxxxxxxxxx To unsubscribe from this list, visit https://urldefense.com/v3/__https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee__;!!ACWV5N9M2RV99hQ!evnGFDawvZ0J77an6ICp1RR9z20hx8PhVpI1bVm_kznDtsW4hKly6_sdM-hMUjw$
Back to the top