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):
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.
- Statement that 'certification of
compatibility' process must be followed before
a compatibility claim can be made
Optional content
- Test coverage document
- Test assertion document
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).
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.
Thanks,
-- Ed
-------- Forwarded Message --------
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?
Thanks Scott.
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.
Hi,
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.
Thanks,
-- Ed
_______________________________________________
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
_______________________________________________
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
--
Mike Milinkovich
Executive Director | Eclipse Foundation AISBL
Twitter:@mmilinkov
|
This email has been checked for
viruses by Avast antivirus software.
www.avast.com
|
_______________________________________________
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$