search

jakartaee / websocket

Jakarta WebSocket
https://projects.eclipse.org/projects/ee4j.websocket
Other
60 stars 42 forks source link

Prepare WebSocket project for Jakarta EE 8 Release #295

Closed m0mus closed 5 years ago

m0mus commented 5 years ago

Tasks

See here for detailed instructions.

joakime commented 5 years ago

The "Generate Stand-alone TCK test results" step isn't possible on this project. This is an API project, it has no implementation code that a TCK could run against.

joakime commented 5 years ago

Same is true for "Submit tests for ballot", this is an API only project.

m0mus commented 5 years ago

It is possible and it's been done by other projects. Please read a how-to guide. If you need help creating a Jenkins job, let me know.

joakime commented 5 years ago

@m0mus I've been looking ...

So far, Servlet is the only other project in the list of projects for Jakarta that is similar to WebSocket. (Servlet also has not done the TCK pieces).

  1. has no implementation.
  2. is a pure API.
  3. has no dependencies on anything else in Jakarta.

The 2nd level Guide assumes you can execute the TCK against your project's code which has an implementation. I think the 2 TCK requirements on WebSocket are meant for the Tyrus project ( https://github.com/eclipse-ee4j/tyrus ), which is the old pre-Jakarta reference implementation for WebSocket.

If we hook up the Jakarta WebSocket API project to the existing compiled websocket-tck.jar (aka the "Stand-alone TCK" in the 2nd level Guide) to this project, it wouldn't produce any test results as it would fundamentally fail to even start/execute due to lack of implementation. (if this is the path, as indicated on the second level Guide, then there's no solution and we would need an exception for the TCK pieces)

If we setup this WebSocket API project to build against all of Glassfish (Not the "Stand-alone TCK" as indicated in the 2nd level Guide, but really the entire TCK ecosystem, as indicated by the 3rd level Guide), then we are not testing this API only project, we are testing the Tyrus project. (If this is the path, then this project and Tyrus will have exactly the same jenkins job, build, and test results, with no difference in git url, branch, etc...)

If we look at what the websocket TCK tests are doing in Glassfish, it tests the existence of the API (provided by Tyrus), and then Tyrus specific integration behaviors (not part of the WebSocket spec), and then Tyrus specific CDI behaviors (which also has never been part of the WebSocket spec, those are part of the CDI spec).

Is this really the goal of the TCK sections of the various levels of the Guide? Not to test or prove the TCK, or the individual Jakarta project artifacts, but to test Glassfish against the entirety of the Jakarta ecosystem? Certainly seems that way.

arjantijms commented 5 years ago

@joakime it currently needs to be tested against a compatible OSS implementation. At the moment that's GF indeed, but could (should) be others in the future.

There are other specs with no dependencies on anything else in Jakarta, like Expression Language, Activation, Bean Validation, Web Services Metadata etc.

The way to test them is to replace the API jar in GF with your jar, then run the TCK. I've done this for Authentication, Authorization, Security, Expression Language and Servlet. It's quite doable, but you can ask for help on the list as not everything might be clear initially (easiest is to start from copying a job/script such as Servlet's)

m0mus commented 5 years ago

I asked @senivam to help setting up TCK jobs for Websocket.

m0mus commented 5 years ago

@joakime can you please update the tasks on the description so it reflects the current state. As I understand TCK jobs are created and text files are also changed. Is it true?

joakime commented 5 years ago

@m0mus TCK jobs were created, no test results in a static location (per Guide level 2, and discussion on various mailing lists), unless you allow for jenkins results to be that static location? Text files are existing PRs, unmerged, awaiting reviews.

joakime commented 5 years ago

Reference to existing PRs for text updates...

m0mus commented 5 years ago

@joakime Thanks for you update. I approved both PRs above. You can merge them.

m0mus commented 5 years ago

@joakime You need to make a staging release first, after that run TCK jobs @senivam created using that jar. You need to take summary.txt file produced by this job and copy it to websocket web site as @bshannon is suggesting.

joakime commented 5 years ago

New PR's submitted for version upgrade to 1.1.2

m0mus commented 5 years ago

@joakime Both merged. Please carry on with a staging release.

senivam commented 5 years ago

promoted to staging: https://oss.sonatype.org/content/groups/staging/jakarta/websocket/jakarta.websocket-api/1.1.2/jakarta.websocket-api-1.1.2.jar

joakime commented 5 years ago

@senivam that's only 1 of the 3 artifacts.

Of the 2 artifacts with packaging jar and bundle, the javadocs do not contain the "Eclipse Foundation Specification License" per the Guide. That stage should be dropped.

senivam commented 5 years ago

@joakime https://oss.sonatype.org/content/groups/staging/jakarta/websocket/jakarta.websocket-api/1.1.2/ https://oss.sonatype.org/content/groups/staging/jakarta/websocket/jakarta.websocket-all/1.1.2/ https://oss.sonatype.org/content/groups/staging/jakarta/websocket/jakarta.websocket-client-api/1.1.2/

joakime commented 5 years ago

I'm aware of that.

The URLs you have provided are part of the global "staging" group, meaning that the actual content is part of a closed staging repository somewhere else (a different URL).

Of the 2 artifacts with packaging jar and bundle, the javadocs do not contain the "Eclipse Foundation Specification License" per the Guide. That stage should be dropped.

$ jar -tvf jakarta.websocket-api-1.1.2-javadoc.jar | grep -i license
$ jar -tvf jakarta.websocket-api-1.1.2-javadoc.jar | grep -i eclipse
$ jar -tvf jakarta.websocket-api-1.1.2-javadoc.jar | grep -i efsl
$ jar -tvf jakarta.websocket-client-api-1.1.2-javadoc.jar | grep -i license
$ jar -tvf jakarta.websocket-client-api-1.1.2-javadoc.jar | grep -i eclipse
$ jar -tvf jakarta.websocket-client-api-1.1.2-javadoc.jar | grep -i efsl
$

No results, the EFSL license is supposed to be included in the Javadoc, per the Guide at https://wiki.eclipse.org/How_to_Prepare_API_Projects_for_the_Jakarta_EE_8_Release

joakime commented 5 years ago

The copyright is present on the individual generated javadoc as ...

<p class="legalCopy"><small>Copyright &#169; 2017-2019 <a href="https://www.eclipse.org">Eclipse Foundation</a>. All Rights Reserved.</small></p>

But that's the Copyright, not the License as indicated by the Guide.

m0mus commented 5 years ago

@joakime It's good that you found it! Can you fix it please and re-stage the artifacts?

joakime commented 5 years ago

I've been attempting to verify the asc / sha1 / md5 on the staged repo, and I came across a slow (took about 3 minutes to obtain the key), but ultimately successful, gpg verify of the artifacts.

$ gpg --auto-key-locate keyserver --keyserver pgp.mit.edu --keyserver-options auto-key-retrieve --verify jakarta.websocket-api-1.1.2.jar.asc jakarta.websocket-api-1.1.2.jar
gpg: Signature made Tue 30 Jul 2019 05:18:05 AM CDT
gpg:                using RSA key F674EBA7B6EC777BDB58942DE0E92C40A43A012A
gpg: requesting key E0E92C40A43A012A from hkp server pgp.mit.edu
gpg: key 718E28A09E67016B: 1 signature not checked due to a missing key
gpg: key 718E28A09E67016B: public key "Eclipse Project for WebSocket <websocket-dev@eclipse.org>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1
gpg: Good signature from "Eclipse Project for WebSocket <websocket-dev@eclipse.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: FFA9 5B1D D22F E6D1 9118  9AFA 718E 28A0 9E67 016B
     Subkey fingerprint: F674 EBA7 B6EC 777B DB58  942D E0E9 2C40 A43A 012A

Do we have a public list of the valid keys somewhere? How about the web of trust and cross signing by the eclipse foundation? (which I would have expected)

joakime commented 5 years ago

@joakime It's good that you found it!

@m0mus a sampling of 5 other projects on the jakarta list of "done" for "Jakarta EE 8 Release" show inconsistent results for the license in the javadoc artifact. (was looking for how other projects did this, as raw resources into a javadoc jar isn't a typically supported features of the maven-javadoc-plugin, well, sort of, but you'd have to setup a resource dependency for the maven-javadoc-plugin to use via it's <resourcesArtifacts> configuration.)

Is this requirement for license files in the javadoc artifact even being tested for during your reviews? (the requirement being listed in the Guide we've been tasked with following)

Example of javadoc artifacts with no license files in them.

However, I did find one, with a odd location, and filename for the license file.

$ jar -tvf jakarta.servlet-api-4.0.3-javadoc.jar | grep -Ei "(license|eclipse|efsl)"
$ jar -tvf jakarta.security.enterprise-api-1.0.2-javadoc.jar | grep -Ei "(license|eclipse|efsl)"
$ jar -tvf jakarta.inject-api-1.0-javadoc.jar | grep -Ei "(license|eclipse|efsl)"
$ jar -tvf jakarta.jms-api-2.0.3-javadoc.jar | grep -Ei "(license|eclipse|efsl)"
$ jar -tvf jakarta.json-api-1.1.6-javadoc.jar | grep -Ei "(license|eclipse|efsl)"
  3250 Fri Jul 19 19:35:18 CDT 2019 doc-files/speclicense.html
$

The typical process (for all other eclipse projects) has to been to put the LICENSE.html or LICENSE.md or LICENSE.txt into the /META-INF/ directory within the jar. But I haven't seen that setup for javadoc jars in the other Jakarta projects. Note: If we look closely at the produced jakarta.<name>-<version>-sources.jar artifacts too, we see an inconsistent LICENSE behavior.

bshannon commented 5 years ago

json-api is doing the right thing.

The license for the javadocs submitted with the specification is different than the license of the project that produces the javadocs. The former is the specliense.html file; the latter is the LICENSE file.

joakime commented 5 years ago

@bshannon I've submitted a email to jakarta.ee-spec.committee@eclipse.org and jakartaee-spec-project-leads@eclipse.org to seek help.

I've also (accidentally) found that many projects are missing the license file in their "sources" classified jars too. (noted in that email)

m0mus commented 5 years ago

@joakime Good question. It's definitely shouldn't be like this. I guess @eclipsewebmaster can answer it. Maybe it's better to submit an Eclipse BugZilla issue with this question.

joakime commented 5 years ago

Opened PR's for the javadoc license concern ...

joakime commented 5 years ago

I've dropped the existing (bad) websocket 1.1.2 stage repository at oss.sonatype.org. The (bad) 1.1.2-RELEASE tag has been deleted from this git repository as well.

senivam commented 5 years ago

@joakime could you please delete branch 1.1.2 as well?

joakime commented 5 years ago

Staging release of 1.1.2 is available at https://oss.sonatype.org/content/repositories/jakartawebsocket-1007

m0mus commented 5 years ago

Thanks @joakime.

Can you please now submit a two PRs to jakartaee/specifications repository. Use this and this as reference.

@senivam Can you please run the TCK job on newly released jar?

joakime commented 5 years ago

I've opened https://bugs.eclipse.org/bugs/show_bug.cgi?id=549695 to get access to publish the TCK.

So that I can have https://eclipse-ee4j.github.io/websocket/TCK-Results.html working for this issue.

m0mus commented 5 years ago

@joakime I see that gh-pages branch is there.

joakime commented 5 years ago

The gh-pages branch was created a few days ago, in prep for the bugzilla.

The bugzilla itself was worked, verified, and closed a few hours ago.

I'm working on preparing the gh-pages branch for proper https://eclipse-ee4j.github.io/websocket-api/ (and TCK results) today. Once that's done the jakartaee/specifications PR can be created.

arjantijms commented 5 years ago

The bugzilla itself was worked, verified, and closed a few hours ago.

That sounds really great! Do you have the URL to that bugzilla request?

joakime commented 5 years ago

The bugzilla itself was worked, verified, and closed a few hours ago.

That sounds really great! Do you have the URL to that bugzilla request?

Same one that was mentioned in prior comment on this issue. https://bugs.eclipse.org/bugs/show_bug.cgi?id=549695

arjantijms commented 5 years ago

Same one that was mentioned in prior comment on this issue. https://bugs.eclipse.org/bugs/show_bug.cgi?id=549695

Ah, that's "access to publish the TCK" of course. Thanks! I'll do the same for the projects I'm involved with then.

joakime commented 5 years ago

Main project website is now available at ...

https://eclipse-ee4j.github.io/websocket-api/

TCK Results are now present at ...

https://eclipse-ee4j.github.io/websocket-api/TCK-Results.html

I'll submit the specification PRs shortly

m0mus commented 5 years ago

@joakime Great job!

m0mus commented 5 years ago

@joakime Just came to mind mind. TCK results are actually have to be published on the CI web site. It means Tyrus, not WebSocket API.

joakime commented 5 years ago

@joakime Just came to mind mind. TCK results are actually have to be published on the CI web site. It means Tyrus, not WebSocket API.

Frustration level is high with me right now.

This TCK subject was brought up earlier in this same issue. (17 days ago, on July 16th). (API vs Impl, Tyrus should be the TCK results holder, etc..)

Why is this changing? After insisting it be done here? (by 3 different people)

It's difficult to follow a Guide that has less and less relevance and accuracy. It's difficult to follow other projects leads when they are apparently doing things wrong too (TCK results, Javadoc artifact contents, generated Javadoc copyright and licensing, Certification process, specification PR process, documentation requirements, etc) I don't see how Jakarta EE 8 will reach it's target date when the goal posts for "done" keep moving at the whim of individuals. Every project in the "Done" column at https://github.com/orgs/eclipse-ee4j/projects/15 is no longer "Done" according to these same individuals (they all have to redo Javadoc at a minimum, which means a new release, or a dropped and re-staged release, with updated website documentation for new apidocs, with new TCK run, and new specifications PR created for each. That's 4 of the 6 checkboxes unchecked and subject to re-do).

I cannot follow the Guide I've been repeatedly told to follow as it is inaccurate, vague, missing detail, and often misleading. Is there a single project, that is "Done", and is API only (no impl), and that has no dependencies on other parts of Jakarta, that can be used as a example of how things are supposed to be done? (this was a question I asked on July 22)

m0mus commented 5 years ago

@joakime I agree everything you said. The rules are keep changing. It's the first release driven by JESP, so there is a lot of clearance. You are not alone. I also committed TCK results to jakartaee/specifications repository first and to jsonb-api after that before making a final (?) move to Yasson.

Are you subscribed to jakartaee-spec-project-leads mailing list? There was one more change requested today -> changing copyrights to Eclipse Foundation.

joakime commented 5 years ago

Are you subscribed to jakartaee-spec-project-leads mailing list? There was one more change requested today -> changing copyrights to Eclipse Foundation.

Yes, I am subscribed. Have been, for a while now. I even mentioned that javadoc change ("Every project in the Done column ...") in my frustration message.

joakime commented 5 years ago

[Fri Aug 2 at 2:29pm CDT] / Updating tasks after conversation with @dblevins

What's Left ...

Restage Tasks:

As a spec lead I must do these tasks:

As a compatible implementation I must do these tasks:

Optional / Recommended:

joakime commented 5 years ago

Opened PR #307 for Copyright updates to javadoc and /spec/src/main/asciidoc/license-efsl.adoc based on discussion in mailing lists.

joakime commented 5 years ago

@m0mus and @senivam I've been reviewing the TCK requirements on ...

... but the TCK we are using for this websocket-api project ...

http://download.eclipse.org/ee4j/jakartaee-tck/jakartaee8-eftl/promoted/eclipse-websocket-tck-1.1.0.zip

Doesn't seem to comply with the TCK requirements listed in

https://github.com/jakartaee/specification-committee/blob/master/process.adoc#materials-for-a-tck-release

How do we fix its missing documentation requirements? This project doesn't have a TCK requirement, as that's the https://github.com/eclipse-ee4j/jakartaee-tck project. It's also unclear how to satisfy the 2 TCK binary requirements outlined above. (a public one on maven central with one license, and a signed one from download.eclipse.org with a different license)

joakime commented 5 years ago

New WebSocket 1.1.2 stage is available at https://oss.sonatype.org/content/repositories/jakartawebsocket-1008/ The various LICENSE files and links all seem to be in place.

m0mus commented 5 years ago

@senivam can you make TCK summary for this jar? https://oss.sonatype.org/content/groups/staging/jakarta/websocket/jakarta.websocket-api/1.1.2/

m0mus commented 5 years ago

@joakime I am not a right person to help with TCK. I guess @bshannon or @edbratt can help. I am recommending posting your questions to jakartaee-tck-dev@eclipse.org mailing list for greater visibility and higher chance to get help.

senivam commented 5 years ago

summary for TCK: summary.txt

dblevins commented 5 years ago

@joakime on the TCK gaps, best thing for us to do is fix it post Jakarta EE 8 release.

Can you please file a Draft PR to the specifications repository as outlined here:

That PR is where we're supposed to be working through the final issues like this. We need to get that PR and move this conversation over there.

joakime commented 5 years ago

Opened Specifications PRs