runtime-role-matrix-live-202607141522-v2/docs/reviewer-verification-checklist.md

Reviewer Verification Checklist

Overview

This checklist provides a systematic approach for reviewing changes in the Runtime Role Matrix project. Use this document alongside scripts/smoke-test.sh for automated verification.

Verification Commands

Automated Smoke Test

# Run smoke test with stdout output
./scripts/smoke-test.sh

# Run smoke test with JSON output
./scripts/smoke-test.sh --json

# Run smoke test and save to file
./scripts/smoke-test.sh --json --output verification-report.json

# Specify reviewer name
./scripts/smoke-test.sh --json --checked-by "your-name"

Individual Verification Steps

If running individual checks instead of the smoke test:

# Build verification
mvn compile -q

# Unit tests
mvn test -q

# Code format compliance (requires checkstyle configuration)
mvn checkstyle:check

# JavaDoc generation
mvn javadoc:javadoc

# Package verification
mvn package -DskipTests -q

# Dependency analysis
mvn dependency:tree -q

# Static analysis (if spotbugs is configured)
mvn spotbugs:check

# Integration tests
mvn verify -q

Checklist Items

1. Build & Compile

• Maven Build: Project compiles without errors

  • Command: mvn compile -q
  • Expected: BUILD SUCCESS

• Package Verification: JAR/package builds successfully

  • Command: mvn package -DskipTests -q
  • Expected: BUILD SUCCESS, artifact created

• Dependency Check: All dependencies resolve correctly

  • Command: mvn dependency:tree -q
  • Expected: No unresolved dependencies

2. Code Quality

• Code Format Compliance: Code follows project style guidelines

  • Command: mvn checkstyle:check
  • Expected: No checkstyle violations
  • Note: Requires checkstyle configuration in pom.xml

• JavaDoc Existence: All public APIs have JavaDoc documentation

  • Command: mvn javadoc:javadoc
  • Expected: JavaDoc generation completes without errors
  • Note: Check for missing/warning JavaDoc in output

• Static Analysis: No critical bugs detected by static analysis

  • Command: mvn spotbugs:check
  • Expected: No high/critical issues
  • Note: SKIP if spotbugs-maven-plugin not configured

3. Testing

• Unit Tests: All unit tests pass

  • Command: mvn test -q
  • Expected: All tests pass, BUILD SUCCESS

• Integration Tests: Integration tests pass (if configured)

  • Command: mvn verify -q
  • Expected: All integration tests pass
  • Note: SKIP if no integration tests exist

4. Documentation

• CHANGELOG Updated: Changes documented in CHANGELOG
• README Updated: Documentation reflects new functionality
• API Documentation: Public API changes documented

5. Security & Compliance

• No Hardcoded Secrets: No credentials or secrets in code
• Dependency Vulnerabilities: No known CVEs in dependencies
  • Command: mvn dependency-check:check (if configured)

Report Generation

Using smoke-test.sh (Recommended)

1. Run the smoke test with JSON output:

   ./scripts/smoke-test.sh --json --output smoke-report.json
   

2. Review the generated JSON file

3. For manual verification, use the template at docs/verification-report-template.json

Manual Report Creation

Create a JSON report matching verification-report-template.json:

{
  "checkedAt": "2026-07-14T15:22:00Z",
  "checkedBy": "reviewer-name",
  "summary": {
    "total": 8,
    "passed": 7,
    "failed": 1
  },
  "items": [
    { "name": "Maven Build", "status": "PASS" },
    { "name": "Unit Tests", "status": "PASS" },
    { "name": "Code Format Compliance", "status": "PASS" },
    { "name": "JavaDoc Existence", "status": "PASS" },
    { "name": "Package Verification", "status": "PASS" },
    { "name": "Dependency Check", "status": "PASS" },
    { "name": "Static Analysis", "status": "SKIP", "reason": "not configured" },
    { "name": "Integration Tests", "status": "FAIL", "command": "mvn verify" }
  ]
}

Exit Codes

Code	Meaning
0	All checks passed
1	One or more checks failed
2	Invalid arguments

Troubleshooting

Common Issues

1. Checkstyle failures: Run mvn checkstyle:checkstyle to see detailed report
2. Test failures: Run mvn test without -q for detailed output
3. Build failures: Check Maven version compatibility (requires 3.6+)

Script Location

The smoke test script is located at: scripts/smoke-test.sh

This path is relative to the project root directory.