Just to remind everyone, most developers just look at the platform
javadocs. When some average developer is looking at some random API
in the Jakarta EE 10 platform javadocs and sees "@since 1.1", how
are they expected to interpret that? The best solution would be to
use the platform version number, but that doesn't work when looking
at an individual API's javadocs. If the number can't be relative to
the javadocs they're looking at, the next best seemed to be to
qualify the number in some way with the name of the spec it refers
to.
Expecting that average developers will trace their way up the
package tree until they find something that tells them what spec the
number refers to seems like too much to me.
Emily Jiang wrote on 7/16/19 9:05 AM:
+1 on option 1 as it still stands correct.
Emily
Perhaps we can have something like "@Since
Java Transaction API 1.1 (TM/copyright Oracle?)"
For now my PR was approved and merged to
remove the name entirely. I (personally) don't
find that too confusing or at least no more
confusing that referencing a non-existent
Jakarta Transactions 1.1. That said, I would be
happy to raise a new PR with any naming
convention the community decides. I see the
following options:
1. @Since 1.1
2. @Since (some agreed way of referencing old
JCP spec name) 1.1
3. @Since (new Jakarta spec name) 1.1
4. Remove @Since entirely
Whatever option we go for though I would hope
that all specs will follow the same convention.
I would be in favour of option 1. with the
addition of whatever metadata (spec name &
version) could be added in javadoc via
package-info.java
- Ray
The reason the spec name
was included is because when all the javadocs
are combined to form the platform javadocs,
it's much less clear what spec "1.1" refers
to.
Using a Jakarta spec name in @since can be
misleading or wrong since we didn't have old
versions of the Jakarta specs. Still, I think
that's better than dropping the spec name
entirely and introducing the ambiguity.
Scott
Stark wrote on 7/15/19 11:42 AM:
The most common
things seems to be to simply drop the
reference to the spec
@since Common Annotations 1.1 ->
@since 1.1
How do we handle "@since"
tags?
For example:
> * @since Common
Annotations 1.1
I'm guessing we leave them
but I wanted to make sure.
- Ray
Right, the staged approach
is what we are going to have
to do.
Just to follow
up on the TCK call
from earlier
today.
Please can we
confirm a decision
for spec leads on
how to deal with
dependencies on
other Jakarta EE
projects in their
poms and whether
to proceed to
staging/TCK runs
before those other
projects release
or whether we will
form some kind of
sequencing?
Perhaps as a
community we could
do it in two
stages? Request an
initial release to
staging this week
with current
dependency sets
then a follow up
release once we
know all the
artifacts are
staged?
Hi,
First, a
message to all
the
specification
project leads:
You are
strongly
encouraged to
join this
mailing list:
We are on a
tight schedule
to get the
Jakarta EE
specifications
ready for the
Jakarta EE 8
Release. I am
in the process
of creating
GitHub issues
in the
projects that
will be
followed up
here: https://github.com/orgs/eclipse-ee4j/projects/15
If you
don't have an
issue created
for you yet,
please feel
free to create
an issue
titled
"Prepare
Jakarta XXX
for the
Jakarta EE 8
Release" with
the following
content in
your issue
tracker:
-----
------
All the
above need to
be done by
July 15 in
order to
follow the
plan for the
Jakarta EE 8
Release.
Ivar
ee4j-pmc mailing
list
ee4j-pmc@xxxxxxxxxxx
To change your
delivery options,
retrieve your
password, or
unsubscribe from
this list, visit
https://www.eclipse.org/mailman/listinfo/ee4j-pmc
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your
delivery options,
retrieve your
password, or
unsubscribe from this
list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
jakartaee-spec-project-leads
mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options,
retrieve your password, or
unsubscribe from this list,
visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
--
_______________________________________________
jakartaee-spec-project-leads mailing
list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options,
retrieve your password, or
unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your
password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
--
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your password,
or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
_______________________________________________
jakartaee-spec-project-leads mailing list
jakartaee-spec-project-leads@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakartaee-spec-project-leads
|
