Peer Review/Testing Checklist

[evelinec]

Peer Review conducted on 3 platforms: Mac, Windows & Linux

• Mac OS is our base OS as the dev content team generally develops on the Mac OS.
• Conduct three separate peer reviews for each OS.

Peer Review: review to be done by a peer member.

Functionality

• Check that the guide has working instructions and sample code
• If any URL visits, try them on different browsers: Firefox, Chrome, Safari
• If any URL visits, try curl command where applicable

Formatting & Presentation

README.adoc checks:

• 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 that the pom.xml, server.xml, etc files are clean
  • 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
• Examples with the right outcomes are provided
• Examples with the wrong outcomes, if any, are provided

pom.xml checks (if files are present):

• Check that the file follows the template found here: https://github.com/OpenLiberty/draft-guides-template/blob/draft/finish/pom.xml
• Check that the following dependencies are included in all of the pom.xml files:

<!-- Provided dependencies -->
<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>8.0.0</version>
  <scope>provided</scope>
</dependency>

<dependency>
  <groupId>org.eclipse.microprofile</groupId
  <artifactId>microprofile</artifactId>
  <version>4.0.1</version>
  <type>pom</type>
  <scope>provided</scope>
</dependency>

• Check that the versions of plugins are directly provided and not fed in by a file property.
  • Not formatted like so:

    <properties>
        <!-- Plugins -->
        <version.liberty-maven-plugin>3.4</version.liberty-maven-plugin>
    </properties>

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>${version.liberty-maven-plugin}</version>
    </plugin>

• Should be formatted like so:

    <!-- Liberty plugin -->
    <plugin>
        <groupId>io.openliberty.tools</groupId>
        <artifactId>liberty-maven-plugin</artifactId>
        <version>3.4</version>
    </plugin>

• Check that there are 4 spaces per indent for proper formatting
• Ensure that the guide is using the latest version of the liberty-maven-plugin or liberty-gradle-plugin where applicable

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, Java 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 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 URL on all browsers, ie, FF, Chrome, Safari
  • Consider testing the curl command for URL visits
  • Make sure the index.html information is correct by visiting the root, e.g. http://localhost:9080
• Consider building with both Maven and Gradle build tools
• Testing with different IDEs, ie, Atom, Eclipse (Optional: VS.code, IntelliJ, Microclimate)
• Run Acrolinx Checker on draft (above 70 score approximately)
• Consider SEO title and description for the guides
• Ensure automated tests with GitHub Actions are enabled
• Run diff -r start/ finish/ and there's no differences
• Ensure that the automation tests are able to run when PR is created
• Check the appearance of the guide on test site for the following items:
  • Table of contents
  • Headings
  • Paragraphs
  • code snippets
  • outputs
  • links
  • hotspots
• Test the guide end-to-end with working instruction and sample code
• Perform all the defined test cases