I agree with Ed here. The links on the PRs should be valid, and the links in the index files should be updated once the PR is merged and the final TCK staged. Really any link in the online content that needs a future event to happen should be a placeholder variable reference that needs to be filled in either by some website magic or by hand when the PR is merged and the links are really available.
My two cents worth: We should be striving to deliver material
that invites review, invites collaboration, provides the details,
wherever and whenever someone in the community engages with our
work. The fact these links are supposed to fail before the ballot
is concluded, would likely be a barrier to that. The fact that we
find the process difficult to understand and implement
correctly probably suggests that anyone outside our confines would
have even less ability (or incentive) to follow the bread crumbs. My personal opinion is, these links ought to work all the time.
If someone wants to read a proposed spec, while it is in the
proposal phase -- we should be inviting and encouraging that. We
may be facile at the working of GitHub and Git, but as ubiquitous
as these tools are, there are folks who won't take the time to
unpack the contents of a PR before it's merged. Kevin, I think you are pointing to a symptom of the complexity
that we have set for ourselves. The fact that even those who
probably knew most clearly what we were intending to accomplish --
yet still got it wrong -- says something about the process we have
created. -- Ed
On 8/30/2019 7:09 AM, Kevin Sutter
wrote:
As I was
looking
at this data, I think maybe the reason that most everyone has
the CR incorrect
is because our Platform and Web Profile CRs were incorrect...
These
were probably used as a "model" for most everybody's CR issue...
https://github.com/eclipse-ee4j/jakartaee-platform/issues/99
https://github.com/eclipse-ee4j/jakartaee-platform/issues/100
---------------------------------------------------
Kevin Sutter
STSM, MicroProfile and Jakarta EE architect
e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
From:
"Steve
Millidge (Payara)" <steve.millidge@xxxxxxxxxxx>
To:
Jakarta
specification committee
<jakarta.ee-spec.committee@xxxxxxxxxxx>
Date:
08/30/2019
08:49 AM
Subject:
[EXTERNAL]
Re: [jakarta.ee-spec.committee] TCK URL inconsistencies
Sent
by: jakarta.ee-spec.committee-bounces@xxxxxxxxxxx
From
my perspective it has been very confusing and quite
frustrating. I think
the issue arises because of the link to artefacts that don’t
exist, obviously
if you are expecting a 404 you can’t check whether what you
have is correct
or not. Won’t
the “nothing is real yet” perpetuate into future releases, at
least for
the first Compatible Implementation? Isn’t this caused by the
chicken
and egg requirement that a spec can’t go final without a
compatible implementation
and a compatible implementation can’t be done until the
spec/tck goes
final? For a following Compatible Implementation things are
much simpler
as the TCK, api jars etc. will be available from a known
download location.
Steve I
agree that it was/is confusing. We tried to catch many of
these during
our reviews of the material, but as you and Ed have
documented, we failed
on catching everything.
I think part of the confusion is because nothing was "real"
yet.
It was difficult for people to put a URL into the various
locations
that had absolutely no data. We hadn't promoted anything yet,
so
there was no model to look at to ensure that the proper URL
was being used.
But, the staging repository was real, so many people just
kept using
that. So, in some cases, I think this was just an anomaly for
this
first release.
We had also made a conscious decision that we knew some of
this data was
going to be inconsistent and we would correct it later.
We have already had the discussion about the duplicate data
between the
CR and the TCK Results. We decided to allow the duplicate
entries
or to have a pointer from the CR to the TCK Results. Most
people
have decided to go the duplication route. In that case, if
they make
the mistake in one location, it's going to show up in the
other.
Personally, I don't think the situation is all that bad. We
will
correct the entries for this release. Add some clearer
instructions
for the entries for the next time, and move on. I'm fine with
tools
if they are easy to create and maintain, but it sounds like
this "spec
lint" tool might be overkill...
---------------------------------------------------
Kevin Sutter
STSM, MicroProfile and Jakarta EE architect
e-mail: sutter@xxxxxxxxxx Twitter:
@kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
From: Bill
Shannon <bill.shannon@xxxxxxxxxx>
To: Jakarta
specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>
Date: 08/29/2019
05:54 PM
Subject: [EXTERNAL]
[jakarta.ee-spec.committee] TCK URL inconsistencies
Sent by: jakarta.ee-spec.committee-bounces@xxxxxxxxxxx
The URL of the TCK needs to appear in 4 places for a
specification review:
- The
text
of the Pull Request
- In
the _index.md
file in the Pull Request
- In
the Compatibility
Certification Request issue
- In
the TCK
Results Summary (because it needs to include a copy of the
Compatibility
Certification Request)
The
first one needs to be the URL of the staged TCK, so that we can
review
it.
The last three need to be the URL that the TCK will appear at
once the
spec is approved, so that these web pages will be valid after
approval.
No one seems to understand that the last three need to be the
same, need
to be different than the first one, and will not be valid at the
time they're
entered.
Ed did an audit of these URLs; see the attached spreadsheet.
The
entries in green are correct. You'll see that almost all of the
#2
- #4 entries are wrong. We're going to correct the ones that we
can,
and ask others to correct the ones we can't.
Given the widespread confusion over this, it raises the issue...
Maybe we're doing the wrong thing?
Maybe we're asking people to do something that's so difficult or
counterintuitive
that they're never going to get it right?
I'm looking for ideas of how to improve the situation.
Obviously the easiest thing for us to do is to improve the
instructions.
I'm highly doubtful that that will be sufficiently effective.
We could invest in a "spec lint" tool that would automate the
detection and reporting of these errors, allowing submitters to
correct
them before we see them. I believe David started something like
this.
I also threw together a script to check these TCK URLs (after
Ed
did the audit by hand, of course). I think this will be useful
for
other issues, but some of these checks will be very ad hoc and
will require
updating with each release.
We could stop asking for the TCK URL in the _index.md file, and
fill that
in for them when we publish the file. (We should also fill in
links
to the SHA-256 and the digital signature.)
We could stop requiring the Compatibility Certification Request
and the
TCK Results summary to have duplicate information and put it in
one place
and link to the other. (Although I understand the rationale for
having
it in both places.)
Anyone have any other ideas?
[attachment "Jakarta-TCK-Tracking 2.xlsx" deleted by Kevin
Sutter/Rochester/IBM]
_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@xxxxxxxxxxx
To change your delivery options, retrieve your password, or
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 change your delivery options, retrieve your password, or
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 change your delivery options, retrieve your password, or 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@xxxxxxxxxxxTo change your delivery options, retrieve your password, or unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee
|
