| [websocket-dev] General Comments, WebSocket Specification and TCK documents |
Hi,
Here are some comments based on reviewing the documents as they exist in the various repositories. In all cases, I just built the material, where needed (in some cases, the documents are just .txt or .html files, directly viewed).
My preference is that you work directly on (submit PRs against) the TCK files in the jakartaee-tck project, but if you don't think that is reasonable, you can try to find a collaborator that is a committer to the jakartaee-tck project who can assist/make these changes for WebSocket 2.
Let me know if you have any further questions,
-- Ed
I believe that the WebSocket 2.0 TCK is passing in the Jakarta EE TCK Jenkins tests. I don't know if the WebSocket team is using independent test runs on a different compatible implementation (maybe Tyrus?). For example WebSocket results from last week are shown here.
[javatest.batch] ******************************************************************************** [javatest.batch] Number of tests completed: 732 (732 passed, 0 failed, 0 with errors) [javatest.batch] Number of tests remaining: 2 [javatest.batch] ******************************************************************************** [javatest.batch] Completed running 732 tests. [javatest.batch] Number of Tests Passed = 732 [javatest.batch] Number of Tests Failed = 0 [javatest.batch] Number of Tests with Errors = 0 [javatest.batch] ********************************************************************************
If you are running a different compatible implementation or
directly from Tyrus, you'll need to provide the results from that
test run.
I did a quick scan of the Specification Document. Generally, this
is in great shape! These comments are minor.
I checked out the current websocket-api repository and built the
specification locally using mvn clean install. My review is based
on the documents that produced:
Running a "default" install target for the specification that is
currently in the websocket-api repository yields a document at
DRAFT / SNAPSHOT status. Please be sure to update the version
checked into the API repo. The target file-names need to be
changed as well. Presumably, this all happens when you update the
document status. (Perhaps I'm not using the proper command line.)
Section 1.5: Version 1.0 was developed under JCP. Version 1.1 was
developed under Eclipse Foundation, Jakarta EE Process. Maybe this
is irrelevant since there was no substantial Spec. document (nor)
changes in 1.1.
Section 7.1.1 -- Should the CDI reference (Muir 2013) be updated to the Jakarta EE 9 version reference? Similarly the reference to the Jakarta EE Platform further in this paragraph. If so, you'd want to consider also update the corresponding bibliography entries as well.
In general, it does not appear this has been revised for Jakarta
EE 9 or WebSocket 2.0. To make revisions, you can work with
someone on the Jakarta EE TCK project committer team, or just
submit PRs against https://github.com/eclipse-ee4j/jakartaee-tck
and we can try to get them reviewed and merged quickly. The use
guide source for WebSocket is in
https://github.com/eclipse-ee4j/jakartaee-tck/tree/master/user_guides/websocket/src/main/jbake/content
I did not check most of the cross-reference links. The few I did check seemed fine.
The footer copyright needs to be updated to add the current
copyright year (2018, 2020), (cf
https://github.com/eclipse-ee4j/jakartaee-tck/blob/master/user_guides/websocket/src/main/jbake/templates/footer.ftl)
All references to version 1.1 need to be updated to 2.0. This includes url references.
All references to Jakarta EE 8 need to be updated to Jakarta EE 9
Any reference to a Platform CI should have it's version updated
(i.e. Eclipse GlassFish 5.1 -> 6.0)
The version needs to be updated to 2.0. The copyright date(s)
need to be updated (change 2019 to 2020). The release date needs
to be updated.
The text lists the wrong e-mail list for questions about the api.
If Tyrus is not the initial compatible implementation, you might consider updating the text in Section 1.2.1.
Section 1.3 -- is Servlet 4.0 still correct, or should it be Servlet 5.0? (1.3.1. first bullet)
Under required software please confirm that all component versions (JDOM and Apache) are still correct.
Under Installation (3) -- 3.2 installing the Software, Follow these steps, (2) (b), please confirm that the file-name for the TCK download bundle is correct.
I presume that under 4.1, "Configuring ..."
sub-bullet 2, sub-sub bullet d should refer to jakartax.servlet-api.jar. Please verify and change if needed.
sub-bullet 3, change "Java EE server" to "Jakarta EE server."
Section 4.3 -- Is Java API correct? (Change to Jakarta API
throughout this section?)
jakartaee-tck/install/websocket/docs/index.html
Must be updated to refer to v2.0.
Specifications link is wrong.
(https://jakarta-ee/specifications... ->
https://jakarta.ee/specifications/...)
Copyright dates must be updated to 2019, 2020.
Update Release Notes pointer to refer to 2.0 version release notes
jakartaee-tck/install/websocket/docs/WebSocketTCK1.1-ReleaseNotes.html
Update for version 2.0 as necessary, update release date.
(Nice to have -- the courier text for "jakarta.websocket" and
"jakarta.websocket.server" (on Firefox) is tiny. Would be nice if
the font point size were increased.
Confirm number of tests (I don't think the number in this file matches against the log summary from above)
Confirm the "Platform Notes" platforms (Mac, Oracle Linux, Windows 10 -- probably all need to be changed).
Confirm the CI that was used to validate the TCK -- probably Tyrus. Possibly also Eclipse GlassFish 6 (pre-release version).
I think I would just change the next to last section header to
remove "JavaTM API for" so it reads: Installing, Setting Up, and
Running the WebSocket TCK" (If you want to add Jakarta WebSocket,
that's fine too.)
Update Copyright date -- 2019->2020.
jakartaee-tck/install/websocket/docs/README.txt
Update for version 2.0 as necessary. Change any reference of RI or Reference Implementation to CI or Compatible Implementation (in my opinion, it's better to spell out Compatible Implementation). Some updates have been made already. For clarity, you may want to refer specifically to Tyrus (if that is the compatible implementation you are using) instead of CI version 2.0.
Check if references (e.g. glassfish5) are still correct (they may
be updated to glassfish6)