170 lines
4.4 KiB
Markdown
170 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
./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`:
|
|
|
|
```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.
|