Peer Review for Mac

[gkwan-ibm]

Review and test this guide by a peer member with the following prespectives

• by Safari

README

• Ensure that command substitutions use the $(cmd) format and not `cmd`
• Ensure that the console output of the integrated tests do not include the [INFO] tab
• Check the quality and presentation of guide according to Structure and Style Guideline
• Check the appearance of the guide:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links (shoud open a new tab)
  • hotspots (should highlight the code correctly)
• Check that the pom.xml, server.xml, and java files etc files are clean on the right code pane
  • Remove any dependencies and features that are not required
  • Ensure that the parent pom.xml files do not contain any dependencies, and all dependencies are specified in the children pom.xml files
  • lines are not too long and wrapped
  • lines are aligned nicely
• Examples with the right outcomes are provided
• Examples with the wrong outcomes, if any, are provided
• Run Acrolinx Checker (above 70 score approximately)

pom.xml

• Check that the file follows the template found here: https://github.com/OpenLiberty/draft-guides-template/blob/draft/finish/pom.xml
• Check that the dependencies and plugins are latest in all of the pom.xml files:
  • jakarta.jakartaee-api
  • microprofile
  • liberty-maven-plugin
  • etc.
• Check that there are 4 spaces per indent for proper formatting
• Check that no tab characters are used

Overall checks:

• Check the consistency of guide with the template and other guides
• Check the quality of code according to the best coding practices
• Check that all licensing statements are properly stated in all files, with the correct year (Should be present in all Java files + the index.html)
• Check that the directories are properly structured
• Check that some of these page-tags are used in a guide: MicroProfile, Maven, Docker, Kubernetes, Gradle, Jakarta EE, Security, Cloud. Only these tags are visible on the website. Latest list here.
• Check the attribution statement is accurate for the guide
• Verify the GitHub Actions scripts, if any, are accurate and consistent with other guides

Additional tests:

• tests where applicable:
  • Define test coverage and review with team (including guide contributor, if available)
  • Define detail test cases
  • Consider corner cases targeting the specific guide
  • Consider corner cases UI tests
  • Consider testing the curl command for localhost URLs
  • Make sure the index.html information is correct by visiting the root, e.g. http://localhost:9080
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
  • import the finish directory and see any complication error, unused import packages, etc
• Consider SEO title and description for the guides
• Ensure automated tests with GitHub Actions are enabled
• Run diff -r start/ finish/ and there is no differences expect tag and end comments
• Ensure that the automation tests are able to run when PR is created
• Test the guide end-to-end with working instruction and sample code with either of the following Java
  • Java 11
  • Java 17
• Perform all the defined test cases

[SiaaG-dev]

Suggestions:

Suggestion 1:
On Safari, the outputs appear going out of the box for both lgdev and the draft site but if I zoom out a little bit, it fits.
There are also no left/right sliders for the outputs on Safari.

Suggestion 2:
Unable to see the tags displayed on Safari.

[gkwan-ibm]

hi @SiaaG-dev It is the site design for mobile or users resize to smaller windows.

[SiaaG-dev]

Hello, ok, sounds good thank you

[SiaaG-dev]

Regarding checklist page-tag part:
I checked that microprofile page-tag used but may need to add the guide name to https://github.com/OpenLiberty/guides-common/blob/prod/guide_tags.json for it to show

[SiaaG-dev]

Another Suggestion:
There are places where the Create statement is used; the Guideline for Structure and Styles states to use this format for Filename:

Current version:

[role="code_command hotspot file=2", subs="quotes"]
----
#Create the bootstrap.properties file for the inventory service.#
`inventory/src/main/liberty/config/bootstrap.properties`
----

[role="code_command hotspot file=3", subs="quotes"]
----
#Create the bootstrap.properties file for the system service.#
`system/src/main/liberty/config/bootstrap.properties`
----

Suggested change:

[role="code_command hotspot file=2", subs="quotes"]
----
#Create the `bootstrap.properties` file for the inventory service.#
`inventory/src/main/liberty/config/bootstrap.properties`
----

[role="code_command hotspot file=3", subs="quotes"]
----
#Create the `bootstrap.properties` file for the system service.#
`system/src/main/liberty/config/bootstrap.properties`
----

• suggesting the same for some of the Replace commands example

[role="code_command hotspot file=1", subs="quotes"]
----
#Replace the SystemClient class.#
`inventory/src/main/java/io/openliberty/guides/inventory/client/SystemClient.java`
----

[SiaaG-dev]

Suggestion:
I wan't able to find the thirdParty tags in the server.xml for below section. If it is removed, I believe it may not impact the display for it.

inventory/server.xml
[source, xml, linenums, role='code_column hide_tags=thirdParty']
----
include::finish/inventory/src/main/liberty/config/server.xml[]
----

[shin19991207]

Regarding checklist page-tag part:
I checked that microprofile page-tag used but may need to add the guide name to https://github.com/OpenLiberty/guides-common/blob/prod/guide_tags.json for it to show

This will be added once we publish the guide to prod.