370 lines
8.4 KiB
Markdown
370 lines
8.4 KiB
Markdown
# Build Quality Gates - Implementation Patterns
|
|
|
|
This document captures the key patterns and practices discovered during the BAIME build-quality-gates experiment.
|
|
|
|
## Three-Layer Architecture Pattern
|
|
|
|
### P0: Critical Checks (Pre-commit)
|
|
**Purpose**: Block commits that would definitely fail CI
|
|
**Target**: <10 seconds, 50-70% error coverage
|
|
**Examples**: Temporary files, dependency issues, test fixtures
|
|
|
|
```makefile
|
|
check-workspace: check-temp-files check-fixtures check-deps
|
|
@echo "✅ Workspace validation passed"
|
|
```
|
|
|
|
### P1: Enhanced Checks (Quality Assurance)
|
|
**Purpose**: Ensure code quality and team standards
|
|
**Target**: <30 seconds, 80-90% error coverage
|
|
**Examples**: Script validation, import formatting, debug statements
|
|
|
|
```makefile
|
|
check-quality: check-workspace check-scripts check-imports check-debug
|
|
@echo "✅ Quality validation passed"
|
|
```
|
|
|
|
### P2: Advanced Checks (Comprehensive)
|
|
**Purpose**: Full validation for important changes
|
|
**Target**: <60 seconds, 95%+ error coverage
|
|
**Examples**: Language-specific quality, security, performance
|
|
|
|
```makefile
|
|
check-full: check-quality check-security check-performance
|
|
@echo "✅ Comprehensive validation passed"
|
|
```
|
|
|
|
## Script Structure Pattern
|
|
|
|
### Standard Template
|
|
```bash
|
|
#!/bin/bash
|
|
# check-[category].sh - [One-line description]
|
|
#
|
|
# Part of: Build Quality Gates
|
|
# Iteration: [P0/P1/P2]
|
|
# Purpose: [What problems this prevents]
|
|
# Historical Impact: [X% of errors this catches]
|
|
|
|
set -euo pipefail
|
|
|
|
# Colors for consistent output
|
|
RED='\033[0;31m'
|
|
YELLOW='\033[1;33m'
|
|
GREEN='\033[0;32m'
|
|
NC='\033[0m'
|
|
|
|
echo "Checking [category]..."
|
|
|
|
ERRORS=0
|
|
# ... check logic ...
|
|
|
|
# Summary
|
|
if [ $ERRORS -eq 0 ]; then
|
|
echo -e "${GREEN}✅ All [category] checks passed${NC}"
|
|
exit 0
|
|
else
|
|
echo -e "${RED}❌ Found $ERRORS [category] issue(s)${NC}"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Error Message Pattern
|
|
|
|
### Clear, Actionable Messages
|
|
```
|
|
❌ ERROR: Temporary test/debug scripts found:
|
|
- ./test_parser.go
|
|
- ./debug_analyzer.go
|
|
|
|
Action: Delete these temporary files before committing
|
|
|
|
To fix:
|
|
1. Delete temporary files: rm test_*.go debug_*.go
|
|
2. Move legitimate files to appropriate packages
|
|
3. Run again: make check-temp-files
|
|
```
|
|
|
|
### Message Components
|
|
1. **Clear problem statement** in red
|
|
2. **Specific items found** with paths
|
|
3. **Required action** clearly stated
|
|
4. **Step-by-step fix instructions**
|
|
5. **Verification command** to re-run
|
|
|
|
## Performance Optimization Patterns
|
|
|
|
### Parallel Execution
|
|
```makefile
|
|
check-parallel:
|
|
@make check-temp-files & \
|
|
make check-fixtures & \
|
|
make check-deps & \
|
|
wait
|
|
@echo "✅ Parallel checks completed"
|
|
```
|
|
|
|
### Incremental Checking
|
|
```bash
|
|
check-incremental:
|
|
@if [ -n "$(git status --porcelain)" ]; then
|
|
CHANGED=$$(git diff --name-only --cached);
|
|
echo "Checking changed files: $$CHANGED";
|
|
# Run checks only on changed files
|
|
else
|
|
$(MAKE) check-workspace
|
|
fi
|
|
```
|
|
|
|
### Caching Strategy
|
|
```bash
|
|
# Use Go test cache
|
|
go test -short ./...
|
|
|
|
# Cache expensive operations
|
|
CACHE_DIR=.cache/check-deps
|
|
if [ ! -f "$CACHE_DIR/verified" ]; then
|
|
go mod verify
|
|
touch "$CACHE_DIR/verified"
|
|
fi
|
|
```
|
|
|
|
## Integration Patterns
|
|
|
|
### Makefile Structure
|
|
```makefile
|
|
# =============================================================================
|
|
# Build Quality Gates - Three-Layer Architecture
|
|
# =============================================================================
|
|
|
|
# P0: Critical checks (must pass before commit)
|
|
check-workspace: check-temp-files check-fixtures check-deps
|
|
@echo "✅ Workspace validation passed"
|
|
|
|
# P1: Enhanced checks (quality assurance)
|
|
check-quality: check-workspace check-scripts check-imports check-debug
|
|
@echo "✅ Quality validation passed"
|
|
|
|
# P2: Advanced checks (comprehensive validation)
|
|
check-full: check-quality check-security check-performance
|
|
@echo "✅ Comprehensive validation passed"
|
|
|
|
# =============================================================================
|
|
# Workflow Targets
|
|
# =============================================================================
|
|
|
|
# Development iteration (fastest)
|
|
dev: fmt build
|
|
@echo "✅ Development build complete"
|
|
|
|
# Pre-commit validation (recommended)
|
|
pre-commit: check-workspace test-short
|
|
@echo "✅ Pre-commit checks passed"
|
|
|
|
# Full validation (before important commits)
|
|
all: check-quality test-full build-all
|
|
@echo "✅ Full validation passed"
|
|
|
|
# CI-level validation
|
|
ci: check-full test-all build-all verify
|
|
@echo "✅ CI validation passed"
|
|
```
|
|
|
|
### CI/CD Integration Pattern
|
|
```yaml
|
|
# GitHub Actions
|
|
- name: Run quality gates
|
|
run: make ci
|
|
|
|
# GitLab CI
|
|
script:
|
|
- make ci
|
|
|
|
# Jenkins
|
|
sh 'make ci'
|
|
```
|
|
|
|
## Tool Chain Management Patterns
|
|
|
|
### Version Consistency
|
|
```bash
|
|
# Pin versions in configuration
|
|
.golangci.yml: version: "1.64.8"
|
|
.tool-versions: golangci-lint 1.64.8
|
|
```
|
|
|
|
### Docker-based Toolchains
|
|
```dockerfile
|
|
FROM golang:1.21.0
|
|
RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64.8
|
|
RUN go install golang.org/x/tools/cmd/goimports@latest
|
|
```
|
|
|
|
### Cross-Platform Compatibility
|
|
```bash
|
|
# Use portable tools
|
|
find . -name "*.go" # instead of platform-specific tools
|
|
grep -r "TODO" . # instead of IDE-specific search
|
|
```
|
|
|
|
## Quality Metrics Patterns
|
|
|
|
### V_instance Calculation
|
|
```bash
|
|
V_instance=$(echo "scale=3;
|
|
0.4 * (1 - $ci_failure_rate) +
|
|
0.3 * (1 - $avg_iterations/$baseline_iterations) +
|
|
0.2 * ($baseline_time/$detection_time/10) +
|
|
0.1 * $error_coverage" | bc)
|
|
```
|
|
|
|
### Metrics Collection
|
|
```bash
|
|
# Automated metrics collection
|
|
collect_metrics() {
|
|
local ci_failure_rate=$(get_ci_failure_rate)
|
|
local detection_time=$(measure_detection_time)
|
|
local error_coverage=$(calculate_error_coverage)
|
|
# Calculate and store metrics
|
|
}
|
|
```
|
|
|
|
### Trend Monitoring
|
|
```python
|
|
# Plot quality trends over time
|
|
def plot_metrics_trend(metrics_data):
|
|
# Visualize V_instance and V_meta improvement
|
|
# Show convergence toward targets
|
|
pass
|
|
```
|
|
|
|
## Error Handling Patterns
|
|
|
|
### Graceful Degradation
|
|
```bash
|
|
# Continue checking even if one check fails
|
|
ERRORS=0
|
|
check_temp_files || ERRORS=$((ERRORS + 1))
|
|
check_fixtures || ERRORS=$((ERRORS + 1))
|
|
|
|
if [ $ERRORS -gt 0 ]; then
|
|
echo "Found $ERRORS issues"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
### Tool Availability
|
|
```bash
|
|
# Handle missing optional tools
|
|
if command -v goimports >/dev/null; then
|
|
goimports -l .
|
|
else
|
|
echo "⚠️ goimports not available, skipping import check"
|
|
fi
|
|
```
|
|
|
|
### Clear Exit Codes
|
|
```bash
|
|
# 0: Success
|
|
# 1: Errors found
|
|
# 2: Configuration issues
|
|
# 3: Tool not available
|
|
```
|
|
|
|
## Team Adoption Patterns
|
|
|
|
### Gradual Enforcement
|
|
```bash
|
|
# Start with warnings
|
|
if [ "${ENFORCE_QUALITY:-false}" = "true" ]; then
|
|
make check-workspace-strict
|
|
else
|
|
make check-workspace-warning
|
|
fi
|
|
```
|
|
|
|
### Easy Fix Commands
|
|
```bash
|
|
# Provide one-command fixes
|
|
fix-imports:
|
|
@echo "Fixing imports..."
|
|
@goimports -w .
|
|
@echo "✅ Imports fixed"
|
|
|
|
fix-temp-files:
|
|
@echo "Removing temporary files..."
|
|
@rm -f test_*.go debug_*.go
|
|
@echo "✅ Temporary files removed"
|
|
```
|
|
|
|
### Documentation Integration
|
|
```bash
|
|
# Link to documentation in error messages
|
|
echo "See: docs/guides/build-quality-gates.md#temporary-files"
|
|
```
|
|
|
|
## Maintenance Patterns
|
|
|
|
### Regular Updates
|
|
```bash
|
|
# Monthly tool updates
|
|
update-quality-tools:
|
|
@echo "Updating quality gate tools..."
|
|
@go install -a github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
|
@make check-full && echo "✅ Tools updated successfully"
|
|
```
|
|
|
|
### Performance Monitoring
|
|
```bash
|
|
# Benchmark performance regularly
|
|
benchmark-quality-gates:
|
|
@for i in {1..10}; do
|
|
time make check-full 2>&1 | grep real
|
|
done
|
|
```
|
|
|
|
### Feedback Collection
|
|
```bash
|
|
# Collect team feedback
|
|
collect-quality-feedback:
|
|
@echo "Please share your experience with quality gates:"
|
|
@echo "1. What's working well?"
|
|
@echo "2. What's frustrating?"
|
|
@echo "3. Suggested improvements?"
|
|
```
|
|
|
|
## Anti-Patterns to Avoid
|
|
|
|
### ❌ Don't Do This
|
|
```bash
|
|
# Too strict - blocks legitimate work
|
|
if [ -n "$(git status --porcelain)" ]; then
|
|
echo "Working directory must be clean"
|
|
exit 1
|
|
fi
|
|
|
|
# Too slow - developers won't use it
|
|
make check-slow-heavy-analysis # Takes 5+ minutes
|
|
|
|
# Unclear errors - developers don't know how to fix
|
|
echo "❌ Code quality issues found"
|
|
exit 1
|
|
```
|
|
|
|
### ✅ Do This Instead
|
|
```bash
|
|
# Flexible - allows legitimate work
|
|
if [ -n "$(find . -name "*.tmp")" ]; then
|
|
echo "❌ Temporary files found"
|
|
echo "Remove: find . -name '*.tmp' -delete"
|
|
fi
|
|
|
|
# Fast - developers actually use it
|
|
make check-quick-essentials # <30 seconds
|
|
|
|
# Clear errors - developers can fix immediately
|
|
echo "❌ Import formatting issues in:"
|
|
echo " - internal/parser.go"
|
|
echo "Fix: goimports -w ."
|
|
```
|