[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [jakarta.ee-spec] [BALLOT COMPLETE] [DISCUSS] Approve the Jakarta TCK package naming convention ee.jakarta.tck.[spec]
|
"Congratulations", you successfully
concluded this ballot - but this might be a Pyrrhic victory:
I think the ballot result is far away
from consensus - even when the intentions might be good - the
result is not feeling like that!
Why:
Let me start with some project
management or systems engineering basics, a short theory on
project structure planing:
Within a project structure plan you
define the structure of a complex system (may be of systems) for
the inside and outside world.
This is done by defining a hierarchy,
that reflects the real world (including reflecting the
environment) in a (tree-)model at best, which divides something
complex into manageable parts that could be referenced.
There are multiple ways to create the
model, for a complex technical system (of systems) it is a good
idea to look at the dependencies between the parts and reflect
coherence to group things together.
The project structure plan reflects
technical and organisational aspects, meaning Conway's Law is
valid in both directions.
Design goal is: Make it as simple as
possible, but not simpler!
Another: One change in the real world
should be one change in the abstracted model.
Example:
PROJECT_STRUCTURE_NODE_ID_1 (this
is a root ID)
PROJECT_STRUCTURE_NODE_ID_1_1
PROJECT_STRUCTURE_NODE_ID_1_1_1
PROJECT_STRUCTURE_NODE_ID_1_2
PROJECT_STRUCTURE_NODE_ID_1_2_1
PROJECT_STRUCTURE_NODE_ID_1_2_2
In the case modelling a system of
systems, the following could be added to the model above:
PROJECT_STRUCTURE_NODE_ID_2 (this is a secondary root ID)
PROJECT_STRUCTURE_NODE_ID_2_1
PROJECT_STRUCTURE_NODE_ID_2_2
The structure and naming of the IDs
need to be well defined, because they are references.
Changes are VERY expensive and the
price is raising from leaf towards root.
Regarding software projects using
Semantic Versioning most of the changes are breaking ones, result
in major releases - one exception might be adding (non required)
leaf nodes, which would result in a minor release.
All software artefacts should reflect
that structure and ID naming consistently in their namespace, but
might have to reflect artefact type naming convention also and
internal structuring additionally.
Another good design principle to omit
conflicts is to have the same depth for every leaf - or at least
all leaves on one node.
Important: There is always a project
structure, if not specified explicitly, it exists implicitly.
For Jakarta EE there is a project
structure defined indirectly (thanks to David pointing this out):
Additionally there is a naming
convention for Maven and OSGi on the eclipse wiki (thanks to Scott
S.):
For JPMS there are references here:
Example:
[Eclipse Foundation AISBL]
Jakarta[ EE]
Jakarta Servlet
Jakarta Server Pages
Jakarta RESTful Web Services
Java package namespace:
jakarta (specs root)
jakarta.servlet.*
jakarta.servlet.jsp.*
jakarta.ws.rs.*
Maven:
jakarta.servlet:jakarta.servlet-api:jar
jakarta.servlet.jsp:jakarta.servlet.jsp-api:jar
jakarta.ws.rs:jakarta.ws.rs-api:jar
OSGi Bundles and JPMS artefacts are
omitted here.
From the organisational perspective not
defined in the existing documents and deviating in much cases are
the names of the jakarta spec mailing lists (but there is a
general naming convention at Eclipse for them).
Important: Root for the package name is
"jakarta" and NOT "ee.jakarta" (for reasons, see first reference
above)!
Note: Not using the same depth in the
structure for specs, like for jakarta.servlet.* and
jakarta.servlet.jsp.* creates an overlap and therefore does not
separate the Java package namespace completely, which could result
in conflicts!
Component specs handled regarding the structure pretty much the
same as umbrella specs, but the naming deviates a little bit in
Jakarta EE profiles.
The platform is organized in a multi module with one version for
the sub-moduls (component specs could be organized the same way).
Implementations of the spec have
relations to the spec too, but tests specific to the
implementation need to be separated from the spec and cohesion is
lower within one single spec.
Implementations (and most user applications too) are not allowed
using the specs namespace (usually jakarta.[SPEC_NAME].*), with
some small exceptions defined (in Paul's legal collection):
https://www.eclipse.org/lists/jakarta.ee-spec/msg02158.html
In general, usually at minimum the root ID (here the hidden
Eclipse and especially Jakarta) is defining the responsible
project organisation and is legally protected.
This exclusivity is necessary to protect the project from abuse of
somebody else.
When somebody thinks, this is not true, unimportant or can be
ignored:
Why we did the namespace change from javax to jakarta?
A few month ago, the decision had been
made to split up the TCK into parts that belong to a specific
spec.
Historically there where reasons not to
put it into the spec project itself, like the non open source
licencing and that it must use a different namespace.
What would be the obvious place to
allocate the spec TCK?
Yes, into the namespace of the spec
project, where the cohesion is the highest between the API and the
spec document itself.
Java package namespace:
jakarta.servlet.*
jakarta.servlet.jsp.*
jakarta.ws.rs.* (exactly:
jakarta.ws.rs.tck.*)
Maven:
jakarta.servlet:jakarta.servlet-tck:jar
jakarta.servlet.jsp:jakarta.servlet.jsp-tck:jar
jakarta.ws.rs:jakarta.ws.rs-tck:jar
On best practice in Java is to use the
exact same namespace for unit tests as the class under test.
The goal here is maintainability: When
a test fails, you know where to look at automatically (and being
able to use package visibility).
You could do the same with integration
tests too, but you might like to make it more explicit by adding
.tck to it, i.e. in Jakarta Restful Webservices
(jakarta.ws.rs.tck.*).
In the case of a failing test with a
fully qualified class name in a stack trace of a log entry or in a
test report, where to file the issue - which organisation, repo or
bug tracker?
Right, this will be decided with the information available form
the fully qualified class name.
But this works well only, when this is not misleading to the wrong
direction...
This consistent project structure is
even more important when looking at projects like Adoptium:
In the Adoptium project, AQAvit test
suites generate additional QA to OpenJDK builds with a lot of
integration tests on top of the official Java SE JCK ( i.e. by
executing the Apache Tomcat tests).
One idea to improve the quality of
Jakarta EE (and Java SE) even further is to let new Java SE
Versions be tested with (even more) Jakarta EE specs and their
implementations.
This offers fast quality feedback to
OpenJDK (downstream) and software running on top of Java SE builds
like Jakarta specs and others (upstream).
While the experts validating their own
implementation with the TCK are usually very experienced,
inconsistencies in the namespace might result in filing potential
issues at the wrong organisation/project.
Meanwhile, a lot of API changes are
planed for Jakarta EE 10, meaning a lot of additional TCK tests
will be added.
On 2021-12-17 the Jakarta Batch spec
asked, where they should migrate their TCK part, then Romain
started with adding concerns about the usage of jakarta.* in
general and now we are in a very intensive, ongoing discussion
(for more detail on the technical aspects, see the parallel
threads)...
But then - with the intention to come
do a decision as fast as possible, may be too fast - this
relative unclear ballot was prepared (with a survey that missed
options) and conducted - with a not very clear voting result
(while having super majority reached).
Technically this ballot for
"ee.jakarta.tck.[spec]" defines a different root ID and another
intermediate ID ("tck") before the leaf spec ID as deviation from
existing spec namespace.
Said short, it wants to create a
complete separate project structure BESIDES jakarta for the TCKs!
This is in fact increasing the
project's complexity and erosion and therefore decreasing
maintainability!
With a high potential for forever...
As far as I know, this was not the
intended result of the separation of the TCK to spec specific TCKs
at all.
Being able to reference dependencies from TCK to TCK (parallel to
the APIs) in a stable way is very important - we might not change
this simply later without high costs (but of course lower than for
API namespace changes).
A simple example for the consequences
of this ballot:
With this parallel structure, when a
spec is moved into Jakarta EE (i.e. from MicroProfile) the spec
doc and the API goes to one new project, the TCK goes to somewhere
else - another new project or being part of one big TCK again?
Must the JESP enhanced to manage the new root?
The other way around is necessary when
moving out of Jakarta EE to a "normal" project - does this feel
right?
Remember: One thing in the real world
should result into one thing in the model...
Another formal aspect of making this
ballot invalid potentially is the following question: Is the
Jakarta EE Specification Committee allowed to create another
project root ID at all?
When not, who is?
When the Jakarta EE Specification
Committee values speed over quality, then I fear Jakarta EE is
heading towards a big ball of mud...
You may have recognised the recent news
from Indonesia:
The parliament decided this week to
move their capital city Jakarta (35 million mega city) to another
island (Borneo instead of Java) with a new name (Nusantara).
Main reason is Jakarta is sinking and
affected by severe flooding - caused by ground water abuse...
This is real mud!
And now they restart a green field (or
better: green jungle) project.
Current budget: 32 billion $
Translated to Jakarta EE, we could do a
clean restart too:
MicroProfile, Spring (both still on the
same island), Python, Typescript or Go to somewhere else...
I instantly hope there is a bright
future for Jakarta EE!
We are collaborating on a remarkable
(and remarkable complex ;-) ) spec project that should value
quality first.
At the moment, I am thinking about: Is
the answer asked by Jakarta Batch one month ago as simple as:
Migrate your TCK from ibm.com.* to
jakarta.batch.tck.*.
I think a little moratorium giving time for discussions and for
finding a even better solution than the existing one would be
helpful now.
Best,
Jan
PS: And than document it, at best
including trying to define a more explicit project structure plan
:-)
Am 21.01.22 um 10:46 schrieb Emily
Jiang via jakarta.ee-spec:
The ballot for the Approve
the Jakarta TCK package naming convention
ee.jakarta.tck.[spec] is now complete! Thank you
for your participation!
| Representative |
Representative
for: |
Vote |
| Kenji Kazumura |
Fujitsu |
0 |
| Tom Watson, Emily Jiang |
IBM |
+1 |
| Ed Bratt, Dmitry Kornilov |
Oracle |
-1 |
| Andrew Pielage, Matt Gill |
Payara |
0 |
| David Blevins, Jean-Louis Monteiro |
Tomitribe |
+1 |
| Ivar Grimstad |
EE4J PMC |
-1 |
| Marcelo Ancelmo, Martijn Verburg |
Participant Members |
+1 |
| Werner Keil |
Committer Members |
+1 |
| Jun Qian |
Enterprise Members |
0 |
| Zhai Luchao |
Enterprise Members |
+1
|
|
Total |
5 |
Non-binding votes:
Scott Marlow -1
Jan Westerkamp -1
The ballot has concluded successfully with super-majority
positive binding votes.
Below is the formula for working out
supermajority positive votes (2/3 out of non abstained
votes):
2/3*(10-3) = 4.6
The package naming convention ee.jakarta.tck.[spec] has
been approved by Jakarta Spec committee as a Jakarta TCK
package name for you to use. You can start using it in
Jakarta EE 10 TCKs if you wish.
Thanks
Emily
Greetings Jakarta EE Specification Committee.
After a long discussion
on the naming convention of the Jakarta TCK namespaces,
the Jakarta community chose the package name: ee.jakarta.tck.[spec].
I need your vote to approve the Jakarta TCK package name
ee.jakarta.tck.[spec]
Per the process, this will be a seven-day ballot,
ending on January 19, 2022, that requires a
Super-majority positive vote of the Specification
Committee members (note that there is no veto).
Community input is welcome, but only votes cast by
Specification Committee Representatives will be counted.
The Specification Committee is composed of
representatives of the Jakarta EE Working Group Member
Companies (Fujitsu, IBM, Oracle, Payara, Tomitribe,
Primeton, and Shandong Cvicse Middleware Co.), along
with individuals who represent the EE4J PMC, Participant
Members, and Committer Members.
Specification Committee representatives, your vote is
hereby requested. Please respond with +1 (positive), 0
(abstain), or -1 (reject). Any feedback that you can
provide to support your vote will be appreciated.
Thanks
--
--
_______________________________________________
jakarta.ee-spec mailing list
jakarta.ee-spec@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec
