refactor: move README-BUILD-GUARD.md to doc/ folder
- Move README-BUILD-GUARD.md from root to doc/ folder for better organization - Update all references in README.md to point to new location - Follows project structure conventions for documentation organization
This commit is contained in:
Matthew Raymer
336
doc/README-BUILD-GUARD.md
Normal file
336
doc/README-BUILD-GUARD.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# Build Architecture Guard - Husky Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
The Build Architecture Guard protects your build system by enforcing
|
||||
documentation requirements through **Git hooks**. When you modify
|
||||
build-critical files, the system automatically blocks commits/pushes
|
||||
until you update `BUILDING.md`.
|
||||
|
||||
## 🎯 **Why Husky-Only?**
|
||||
|
||||
**Advantages:**
|
||||
|
||||
- ✅ **Immediate feedback** - Hooks run before commit/push
|
||||
- ✅ **Works everywhere** - No server-side CI/CD required
|
||||
- ✅ **Simple setup** - One tool, one configuration
|
||||
- ✅ **Fast execution** - No network delays or server queues
|
||||
- ✅ **Offline support** - Works without internet connection
|
||||
|
||||
**Trade-offs:**
|
||||
|
||||
- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify`
|
||||
- ⚠️ **Developer discipline** - Relies on team following the rules
|
||||
|
||||
## 🏗️ **Architecture**
|
||||
|
||||
```bash
|
||||
Developer Workflow:
|
||||
1. Modify build files (scripts/, vite.config.*, etc.)
|
||||
2. Try to commit → Husky pre-commit hook runs
|
||||
3. Guard script checks if BUILDING.md was updated
|
||||
4. ✅ Commit succeeds if docs updated
|
||||
5. ❌ Commit blocked if docs missing
|
||||
```
|
||||
|
||||
## 🚀 **Quick Start**
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run prepare # Sets up Husky hooks
|
||||
```
|
||||
|
||||
### 2. Test the System
|
||||
|
||||
```bash
|
||||
# Modify a build file without updating BUILDING.md
|
||||
echo "# test" >> scripts/test.sh
|
||||
|
||||
# Try to commit (should be blocked)
|
||||
git add scripts/test.sh
|
||||
git commit -m "test: add build script"
|
||||
# ❌ Hook blocks commit with helpful message
|
||||
```
|
||||
|
||||
### 3. Fix and Retry
|
||||
|
||||
```bash
|
||||
# Update BUILDING.md with your changes
|
||||
echo "## New Build Script" >> BUILDING.md
|
||||
echo "Added test.sh for testing purposes" >> BUILDING.md
|
||||
|
||||
# Now commit should succeed
|
||||
git add BUILDING.md
|
||||
git commit -m "feat: add test build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🔧 **How It Works**
|
||||
|
||||
### Pre-commit Hook (`.husky/pre-commit`)
|
||||
|
||||
- **When**: Every `git commit`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --staged`
|
||||
- **Result**: Blocks commit if build files changed without BUILDING.md update
|
||||
|
||||
### Pre-push Hook (`.husky/pre-push`)
|
||||
|
||||
- **When**: Every `git push`
|
||||
- **What**: Runs `./scripts/build-arch-guard.sh --range`
|
||||
- **Result**: Blocks push if commits contain undocumented build changes
|
||||
|
||||
### Guard Script (`scripts/build-arch-guard.sh`)
|
||||
|
||||
- **Detects**: Changes to build-sensitive file patterns
|
||||
- **Validates**: BUILDING.md was updated alongside changes
|
||||
- **Reports**: Clear error messages with guidance
|
||||
|
||||
## 📁 **Protected File Patterns**
|
||||
|
||||
The guard script monitors these paths for changes:
|
||||
|
||||
```text
|
||||
Build Configuration:
|
||||
├── vite.config.* # Vite configuration
|
||||
├── capacitor.config.ts # Capacitor configuration
|
||||
├── package.json # Package configuration
|
||||
├── package-lock.json # Lock files
|
||||
├── yarn.lock
|
||||
└── pnpm-lock.yaml
|
||||
|
||||
Build Scripts:
|
||||
├── scripts/** # All build and automation scripts
|
||||
├── electron/** # Electron build files
|
||||
├── android/** # Android build configuration
|
||||
├── ios/** # iOS build configuration
|
||||
├── sw_scripts/** # Service worker scripts
|
||||
└── sw_combine.js # Service worker combination
|
||||
|
||||
Deployment:
|
||||
├── Dockerfile # Docker configuration
|
||||
└── docker/** # Docker services
|
||||
```
|
||||
|
||||
## 🎭 **Usage Scenarios**
|
||||
|
||||
### Scenario 1: Adding a New Build Script
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
git add scripts/new-build.sh
|
||||
git commit -m "feat: add new build script"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo '#!/bin/bash' > scripts/new-build.sh
|
||||
echo '## New Build Script' >> BUILDING.md
|
||||
echo 'Added new-build.sh for feature X' >> BUILDING.md
|
||||
git add scripts/new-build.sh BUILDING.md
|
||||
git commit -m "feat: add new build script with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
### Scenario 2: Updating Vite Configuration
|
||||
|
||||
```bash
|
||||
# ❌ This will be blocked
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
git add vite.config.ts
|
||||
git commit -m "config: add new vite option"
|
||||
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated"
|
||||
|
||||
# ✅ This will succeed
|
||||
echo 'export default { newOption: true }' >> vite.config.ts
|
||||
echo '### New Vite Option' >> BUILDING.md
|
||||
echo 'Added newOption for improved performance' >> BUILDING.md
|
||||
git add vite.config.ts BUILDING.md
|
||||
git commit -m "config: add new vite option with docs"
|
||||
# ✅ Commit succeeds
|
||||
```
|
||||
|
||||
## 🚨 **Emergency Bypass**
|
||||
|
||||
**⚠️ Use sparingly and only for emergencies:**
|
||||
|
||||
```bash
|
||||
# Skip pre-commit hook
|
||||
git commit -m "emergency: critical fix" --no-verify
|
||||
|
||||
# Skip pre-push hook
|
||||
git push --no-verify
|
||||
|
||||
# Remember to update BUILDING.md later!
|
||||
```
|
||||
|
||||
## 🔍 **Troubleshooting**
|
||||
|
||||
### Hooks Not Running
|
||||
|
||||
```bash
|
||||
# Reinstall hooks
|
||||
npm run prepare
|
||||
|
||||
# Check hook files exist and are executable
|
||||
ls -la .husky/
|
||||
chmod +x .husky/*
|
||||
|
||||
# Verify Git hooks path
|
||||
git config core.hooksPath
|
||||
# Should show: .husky
|
||||
```
|
||||
|
||||
### Guard Script Issues
|
||||
|
||||
```bash
|
||||
# Test guard script manually
|
||||
./scripts/build-arch-guard.sh --help
|
||||
|
||||
# Check script permissions
|
||||
chmod +x scripts/build-arch-guard.sh
|
||||
|
||||
# Test with specific files
|
||||
./scripts/build-arch-guard.sh --staged
|
||||
```
|
||||
|
||||
### False Positives
|
||||
|
||||
```bash
|
||||
# If guard blocks legitimate changes, check:
|
||||
# 1. Are you modifying a protected file pattern?
|
||||
# 2. Did you update BUILDING.md?
|
||||
# 3. Is BUILDING.md staged for commit?
|
||||
|
||||
# View what the guard sees
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
## 📋 **Best Practices**
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Update BUILDING.md first** - Document changes before implementing
|
||||
2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing
|
||||
3. **Use descriptive commits** - Include context about build changes
|
||||
4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies
|
||||
|
||||
### For Teams
|
||||
|
||||
1. **Document the system** - Ensure everyone understands the guard
|
||||
2. **Review BUILDING.md updates** - Verify documentation quality
|
||||
3. **Monitor bypass usage** - Track when hooks are skipped
|
||||
4. **Regular audits** - Check that BUILDING.md stays current
|
||||
|
||||
### For Maintainers
|
||||
|
||||
1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed
|
||||
2. **Monitor effectiveness** - Track how often the guard catches issues
|
||||
3. **Team training** - Help developers understand the system
|
||||
4. **Continuous improvement** - Refine patterns and error messages
|
||||
|
||||
## 🚨 **Troubleshooting**
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### mapfile Command Not Found
|
||||
|
||||
**Problem**: Pre-commit hook fails with `mapfile: command not found`
|
||||
|
||||
**Cause**: The `mapfile` command is bash-specific and not available in all shell environments
|
||||
|
||||
**Solution**: The script has been updated to use portable alternatives. If you encounter this issue:
|
||||
|
||||
```bash
|
||||
# Verify the script is executable
|
||||
chmod +x scripts/build-arch-guard.sh
|
||||
|
||||
# Test the script directly
|
||||
./scripts/build-arch-guard.sh --help
|
||||
|
||||
# Check your shell environment
|
||||
echo $SHELL
|
||||
bash --version
|
||||
```
|
||||
|
||||
**Prevention**: Ensure your development environment uses bash and the script has proper permissions
|
||||
|
||||
### False Positives
|
||||
|
||||
```bash
|
||||
# If guard blocks legitimate changes, check:
|
||||
# 1. Are you modifying a protected file pattern?
|
||||
# 2. Did you update BUILDING.md?
|
||||
# 3. Is BUILDING.md staged for commit?
|
||||
|
||||
# View what the guard sees
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
## 🔄 **Customization**
|
||||
|
||||
### Adding New Protected Paths
|
||||
|
||||
Edit `scripts/build-arch-guard.sh`:
|
||||
|
||||
```bash
|
||||
SENSITIVE=(
|
||||
# ... existing patterns ...
|
||||
"new-pattern/**" # Add your new pattern
|
||||
"*.config.js" # Add file extensions
|
||||
)
|
||||
```
|
||||
|
||||
### Modifying Error Messages
|
||||
|
||||
Edit the guard script to customize:
|
||||
|
||||
- Error message content
|
||||
- File pattern matching
|
||||
- Documentation requirements
|
||||
- Bypass instructions
|
||||
|
||||
### Adding New Validation Rules
|
||||
|
||||
Extend the guard script to check for:
|
||||
|
||||
- Specific file content patterns
|
||||
- Required documentation sections
|
||||
- Commit message formats
|
||||
- Branch naming conventions
|
||||
|
||||
## 📚 **Integration with PR Template**
|
||||
|
||||
The `pull_request_template.md` works with this system by:
|
||||
|
||||
- **Guiding developers** through required documentation
|
||||
- **Ensuring consistency** across all build changes
|
||||
- **Providing checklist** for comprehensive updates
|
||||
- **Supporting L1/L2/L3** change classification
|
||||
|
||||
## 🎯 **Success Metrics**
|
||||
|
||||
Track the effectiveness of your Build Architecture Guard:
|
||||
|
||||
- **Hook execution rate** - How often hooks run successfully
|
||||
- **Bypass frequency** - How often `--no-verify` is used
|
||||
- **Documentation quality** - BUILDING.md stays current
|
||||
- **Build failures** - Fewer issues from undocumented changes
|
||||
- **Team adoption** - Developers follow the process
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active protection system
|
||||
**Architecture**: Client-side Git hooks only
|
||||
**Dependencies**: Husky, Git, Bash
|
||||
**Maintainer**: Development team
|
||||
**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh`
|
||||
|
||||
## 📝 **Changelog**
|
||||
|
||||
### 2025-08-22 - Shell Compatibility Fix
|
||||
- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility
|
||||
- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks
|
||||
- **Files**: `scripts/build-arch-guard.sh`
|
||||
- **Testing**: Script now works across different shell environments
|
||||
Reference in New Issue
Block a user