[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[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.
WebSocket 2.0 Specification
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.
Review of the TCK Users Guide
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.
All pages
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)
title.html
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.
preface.html
The text lists the wrong e-mail list for questions about the api.
intro.html
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)
install.html
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.
config.html
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?)
Other TCK Documents
The Jakarta WebSocket 2.0 TCK "ReadMe" file
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
Jakarta WebSocket 2.0 TCK "Release Notes" file
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.
Jakarta WebSocket 2.0 "Readme.txt" file
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)