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.)
It seems like cross posting is allowed between 2/3 mailing lists. Forward works for most mail clients. One alternative is to just start a brand new email thread with a web link to the existing conversation. Another alternative could be to use an issue tracker for the discussion as some people prefer discussion in issues over joining different mailing lists.
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):
Required:
The binary TCK, one with the project license, one with the
EFTL license
TCK is to be delivered as a final artifact and is not to be
re-built by the certifying user/organization.
User Guide (or equivalent)
Software requirements
Installation and configuration
How to run the tests
Where to file challenges
TCK Rules not covered in the process guide
Instructions describing how to run the compatible
implementation(s) that are being used to validate the TCK
Top-level README pointing to each of the preceding documents
Recommended:
URLs for issue trackers for certification requests, bug
reports, etc.
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
If the Spec. committer group wishes, can they produce a single
dual-licensed (project license + EFTL license) artifact (zip or
jar)?
Is a single artifact that contains all of the above a
requirement? Otherwise if multiple artifacts are allowed (i.e. a
run-time JAR, an expanded Source JAR, etc.), how would these to
be tracked (SHA-1 vs. SHA-256, for example)? Multiple SHA sums
(I'd presume).
Perhaps we could consider allowing certificate of compabilty request (CCR) to use the Maven GroupID, ArtifactID, version (GAV) which uniquely identifies a particular TCK artifact deployed to the Maven repository. Such that CCRs could contain a well known SHA or GAV.
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.
+1
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.
As a user, I prefer to use an archive that contains all needed dependencies in the archive, this could be a Maven Uber (there are other names for this also) jar.
If we decide that the CCR still needs to use a SHA, the SHA sum could be based on the Maven Uber jar file.
IMO, this feels like an EE 11 change to me, just because it might be confusing to start discussing a change like this, when various SPEC API TCKs are nearly complete for EE 10.
What do others think?
Scott
Thanks,
-- Ed
-------- Forwarded Message --------
Subject:
Re: [jakarta.ee-spec.committee] [External] : Re: TCK
archive format? (Consider allowing JAR or ZIP)
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:
The license must be dual license -- EFTL + EPL (EFTL is not
a compatible open-source license with Sonatype's ToU). I
believe this dual license should be available for Spec. teams
to include (i.e. we ought not recommend Spec. teams
concatenate these licenses together on their own)
The source-code that comes from refactored TCKs from the
Jakarta EE Platform TCK includes EPL + GPLv2 headers. I do not
believe that we expect to alter these headers. However, the
TCK use license, for certification must be EFTL. Since this
has been vetted previously, I will presume, so long as the
EFTL + EPL license is included in our approved manifest
location, we can continue in this fashion. I don't know if
anyone at Eclipse needs to review any of this. (This point is
independent of using Maven as a publication platform)
The User Guide (Reference Guide, Readme) must be available
(either included in the run-time JAR, or perhaps included in
the sources bundle) or we must include a reference that
directs the user to obtain and understand it prior to
submitting a certification request. These documents may be
many pages and include images. In previous Jakarta releases
these are provided in both HTML and PDF format.
Since the User Guide (etc.) is part of the normative
requirements for a specification, if we allow / recommend
these be included in a separate archive, we will need to track
SHA Sums of all the normative document/archives.
Currently we require a SHA-256 sum. Sonatype provides SHA-1.
When we approve use of Maven, should we allow SHA-1 instead?
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.
Thanks,
-- Ed
On 12/9/2021 8:57 AM, Ed Bratt wrote:
Mike,
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.
-- Ed
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.
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?
-- Ed
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?
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.)
-- Ed
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.
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.
Comments?
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.