I would like to share my thoughts on
this topic with a little example:
Project structure:
Jakarta
Jakarta Spec A
Spec A Document
Spec A API
Spec A TCK
Jakarta Spec B
Spec B Document
Spec B API
Spec B TCK
Jakarta Spec C
Spec C Document
Spec C API
Spec C TCK
Implementation Project X
Implementation X_A
Implementation X_B
Implementation Project Y
Implementation Y_A
Implementation Y_C
Dependency graph:
Jakarta Spec A
Jakarta Spec B
Jakarta Spec C
In this example Jakarta Spec A is an umbrella spec (in a general
sense, see below) and Jakarta Spec B and Jakarta Spec C could be
independent component specs.
I think, we agree that only final artefacts reflect a version,
that is intended to be used by common application developers (end
users).
And these final versions need to end up in Maven Central (as sync
point for end users).
We want to have one single version for a single Jakarta spec
(meaning for the spec document, API and TCK of the spec) to show
what belongs together.
That version (and only that) is under control of the Jakarta spec
project and governance of the Jakarta EE Specification Committee -
implementation projects versions are not.
To be clear: If an implementation project decided not to use
SemVer and orders versions by approaching Euler, Pi or use a count
down, they are free to do so - even when this is not reflecting
common user expectations ;-)
However, it is a good idea to ensure SemVer for all of the Jakarta
specs (including the platform/profile/umbrella specs on my
opinion, but that might be a different discussion).
By the way, the same is true for implementation project structure
changes: I.e. renaming implementation X_A to A_X would be out of
scope and therefore control of Jakarta.
One requirement for a Jakarta spec to become final is, that at
least one implementation passes the required TCK (or in some cases
TCKs, exactly spec TCK + global TCK part at the currently for some
specs, but let's assume this fact is covered in the spec TCK
itself) successfully to ensure that a spec is implementable and
therefore useful at all.
In the example above that means one of implementation X_A or
implementation Y_A at least has to pass the Jakarta Spec A
required TCK successfully.
To achieve that, the artefacts need to be referenceable and
loadable by the implementation projects at minimum, but not
necessarily from Maven Central.
This artefact repo should be permanent:
Reproducibility is important!
Out of scope and control of Jakarta there might be issues, that
are influenced by the environment: Jenkins, Maven, Java SE,
Container Runtime, OS, VM, Hardware, physical environment etc.
Even when they are rare, they are usually hard to find - being
able to exclude the issue is within Jakarta itself, it is very
helpful to be able reproduce it at any time.
That requirement results in the exact implementation artefact need
to be available permanently too.
Side note: The cooperation with Adoptium could help regarding Java
SE and to some degree OS changes.
Staging is not fulfilling the requirement at the moment, so
pushing Ms and RCs to Maven Central as a sync point may be a
workaround.
For the future, me might put these artefacts to a Maven repo under
governance of EF to achieve that permanently without confusing end
users (but that's another discussion too).
As David pointed out, we need to define the TCK process and it's
technical implementation not for the happy path only - tests will
fail and the root cause may be in ANY artefact involved, that
might need to be fixed!
So I am with Emily, even the TCK could not be final at the
beginning, when we want to be able to fix it and end up with one
single version for the single Jakarta spec version.
When the TCK run is successful, a final spec version can be
released with a ballot approves it.
Having final artefacts available somewhere (like in Staging)
before the TCK has been passed could cause other problems too: It
is quite best practice to cache Maven - on the organisational
border and locally at the devs machine - most of them is out of
control of Jakarta to withdraw a version and invalidate caches!
So better try not to do that in any case.
We want to have the requirement that final versions of a spec have
only final dependencies (that is not fulfilled in Jakarta EE 9.1
Platform, unfortunately - as discussed yesterday in the platform
call), but an M or RC release could have M, RC or final version
dependencies.
That results in releasing final spec releases from the leaf to
root in the dependency tree, where another source of final release
dependencies might result from unchanged final spec dependencies
of earlier releases.
In the example above this means, Jakarta Spec B and Jakarta Spec C
need to become final before Jakarta Spec A can be.
We also want to ensure in a more complex dependency tree, that
multiple versions of one spec are not allowed, especially major
versions not (that's not fulfilled in 9.1 too)!
Both requirements could be ensured by automatic testing in the
future.
TCKs should be able to reference tests from TCKs of dependent
specs to ensure compatibility (may be partly) - therefore
references need to be stable.
One option to achieve that would be code duplication (antipattern)
or executing the dependent tests directly (that in fact what the
platform TCK might do in the future, partly now and therefore my
vote for a clean project structure with resulting clean namespaces
- but again, that will be discussed somewhere else... ;-) ).
One theoretical example, for having to fix a dependent final spec
(including one of the involved TCKs) might be if only the
combination of multiple dependent specs result in an issue that
prevents the technical combination of the two technologies at all
at the higher level. I.e. Jakarta Spec A can not combine
successful already released Jakarta Spec B and Jakarta Spec C
final versions. This results in a new final release need to be
done at least at one of the leaf dependent specs to be able to
combine them in Jakarta Spec A. When they are in a M or RC state,
it can be fixed easier with another RC before all could become
final at least.
Note: This all is true for all specs with dependencies, which make
them to (or let them behave like) umbrella specs like the profiles
(Platform aka Full Profile, Web Profile and Core Profile including
profiles and optional Jakarta specs like NoSQL) to some degree (!)
I hope this will be helpful for clarifying the TCK process and
implementation.
May be, it's worth to think about a
change in the Eclipse Foundation Technology Compatibility Kit
License (
https://www.eclipse.org/legal/tck.php), if this is
necessary with the split up TCKs?
Best,
Jan
Am 26.01.22 um 15:10 schrieb Scott
Stark:
Because TCKs and APIs are not the same thing. You
cannot make a compatibility claim using APIs. You do not get
essential patent rights based on your API version. Both of those
things are done under the current TCK process using the final
TCK that has the Eclipse Foundation Technology Compatibility Kit
License (
https://www.eclipse.org/legal/tck.php)
which only the final version of the TCK should have bundled.
This is the current TCK process and to allow ratifying
compatible implementations to use non-final TCKs would require
some EFSP change.
You can release a TCK whenever you want. I don't
see what benefit you are deriving from ratifying using a
non-final TCK. Both the scope of scope of essential patents and
grant of those patents derive from the final specification and
final TCK. The benefit of non-final APIs is that it simplifies
the circular nature of having to produce a compatible
implementation to ratify the final API, spec and TCK. The final
TCK becomes the source of truth relative to whether the
compatible implementation has appropriate APIs and behavior.
Why can't TCKs adopt the same process as the APIs? As
long as we prove the RC is the same as the final staging
artifact, we are all good. This is what I suggested:
Raise a RC for both APIs and TCKs - let compatible
implementation to ratify the artifacts with CCRs
Stage final APIs and TCKs - ballot open with the
above CCRs to vote the staged artifacts.
I think the current process of staging TCK final is
ok because TCKs and specs are in separate repos. Once
they all end up under one repo, the api and tcks will be
released together. When you do a RC for API, you will
have a RC for TCK. I don't get why using the same
release of TCK RC is not acceptable.
Thanks
Emily
The TCK cannot be an RC as it is part
of the specification commit project PR that is being
balloted on for final ratification. At that point
there needs to be a staged final API artifact,
specifications, java doc, and TCK. The compatibility
request is verified against the final candidate TCK
referenced in the PR. If the ratification ballot
passes, the staged TCK is promoted to the final TCK
without modification. All that process does is add
the signing signatures of the specification
committee.
+1 on clarifying this.
For rectifying a spec, the viable
solution is to use release candidates for
both APIs and TCKs to avoid chicken egg
situations.
It has been a requirement that the TCK
used for certification was the proposed
final TCK, but not the APIs.
Based on what I said above, TCKs used for
ratifying a spec can be a RC as well. This
will certainly help with the specs that
contain both APIs and TCKs.
Thanks
Emily
Agree.
If the signature tests pass, all is fine and
the vendor is allowed to use their own API
jars. In some cases those API jars are
implementations: Faces, Activation, Mail,
etc. There are other situations like JACC
where the API jar can't really be considered
an implementation, but there is definitely
significant code there.
We'd likely want to document those
requirements in the JESP as the EFSP is what
currently holds the open source requirement.
We may need to add some clarification on the
API jars produced by specification projects
as people are increasingly referring to them
as "the official" jars, implying 1) all
other jars are not official or lesser and 2)
they must be used by the compatible
implementation used for ratification.
Neither is the case. We need some explicit
text that says we have no concept of "the
official" jars and any jars that pass the
TCK and signature tests are equivalent.
For Jakarta EE 8 our compatible
implementation was a pre-Eclipse version of
GlassFish that did not ship the jars
produced by the Specification Projects. We
did do some work to ensure the Specification
Project-produced jars could pass a TCK run.
If we have thoughts that this should or does
not need to happen again if a compatible
implementation does not use the
Specification Project-produced jars, we
should write that down too.
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
> On Jan 25, 2022, at 9:28 AM, Scott
Stark <starksm64@xxxxxxxxx>
wrote:
>
> An issue that came up during the
platform call was what are the requirements
for the compatible implementation that is
used to ratify a specification. A
specification team had decided that they
could not produce an RC that could be used
for such a ratification based on their
interpretation of the following two document
statements:
>
> • According to https://www.eclipse.org/projects/handbook/#specifications-implementations
“Compatible Implementations may only claim
compatibility with a final specification.
... No claims regarding compatibility may be
made for an implementation milestone build
or unratified specification version."
> • https://github.com/jakartaee/specifications/blob/master/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md,
which states, "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."
>
> If I look really pedantically at these
two statements, maybe I could read that only
final APIs can be used by a compatible
implementation, but this is also ignoring
other discussions we have had about the
special nature of the compatible
implementation used to ratify a
specification.
>
> We need to make a clear statement about
the requirements for the initial compatible
implement(s) used to ratify a specification
as well as any additional constraints on
post ratification compatible implementation
claims.
>
> It has been common practice in EE and
MP to use ratifying compatible
implementations that do depend on release
candidate APIs. It has been a requirement
that the TCK used for certification was the
proposed final TCK, but not the APIs. By
virtue of passing the TCK signature tests,
whatever API versions the compatible
implementation used, they have been
validated as compatible as determined by the
final TCK. This should be a sufficient
validation of the compatible implementation.
>
> Let's discuss tomorrow.
>
>
_______________________________________________
> jakarta.ee-spec mailing list
> jakarta.ee-spec@xxxxxxxxxxx
> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec
_______________________________________________
jakarta.ee-spec mailing list
jakarta.ee-spec@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec
--
--
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
