forked from jsnbuchanan/crowd-funder-for-time-pwa
Merge branch 'master' into android-safe-area-insets
This commit is contained in:
Jose Olarte III
248
.cursor/rules/architecture/build_testing.mdc
Normal file
248
.cursor/rules/architecture/build_testing.mdc
Normal file
@@ -0,0 +1,248 @@
|
||||
# Build Testing — Requirements and Emergency Procedures
|
||||
|
||||
> **Agent role**: Reference this file for testing requirements and
|
||||
emergency procedures when working with build architecture changes.
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### Build System Broken
|
||||
|
||||
1. **Immediate**: Revert to last known working commit
|
||||
|
||||
2. **Investigation**: Create issue with full error details
|
||||
|
||||
3. **Testing**: Verify all platforms work after revert
|
||||
|
||||
4. **Documentation**: Update `BUILDING.md` with failure notes
|
||||
|
||||
### Platform-Specific Failure
|
||||
|
||||
1. **Isolate**: Identify which platform is affected
|
||||
|
||||
2. **Test Others**: Verify other platforms still work
|
||||
|
||||
3. **Rollback**: Revert platform-specific changes
|
||||
|
||||
4. **Investigation**: Debug in isolated environment
|
||||
|
||||
## Rollback Playbook
|
||||
|
||||
### Immediate Rollback
|
||||
|
||||
1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config
|
||||
|
||||
files
|
||||
|
||||
2. Rebuild affected targets; verify old behavior returns
|
||||
|
||||
3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found
|
||||
|
||||
### Rollback Verification
|
||||
|
||||
- **Web**: `npm run build:web:dev` and `npm run build:web:prod`
|
||||
|
||||
- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`
|
||||
|
||||
- **Desktop**: `npm run build:electron:dev` and packaging commands
|
||||
|
||||
- **Clean**: Run relevant `clean:*` scripts and verify re-build works
|
||||
|
||||
### Android-Specific Rollback Verification
|
||||
|
||||
- **Asset Generation**: `npm run build:android --assets` -
|
||||
|
||||
verify resources regenerate
|
||||
|
||||
- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
|
||||
|
||||
- **Resource Validation**:
|
||||
|
||||
Check `android/app/src/main/res/` for all required assets
|
||||
|
||||
- **Build Modes**: Verify development, test, and production modes all work
|
||||
|
||||
- **Resource Fallback**:
|
||||
|
||||
Confirm missing resources trigger automatic regeneration
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With Version Control
|
||||
|
||||
- **Branch Protection**: Require reviews for build script changes
|
||||
|
||||
- **Commit Messages**: Must reference ADR for major changes
|
||||
|
||||
- **Testing**: All build changes must pass CI/CD pipeline
|
||||
|
||||
### With Documentation
|
||||
|
||||
- **BUILDING.md**: Must be updated for any script changes
|
||||
|
||||
- **README.md**: Must reflect new build requirements
|
||||
|
||||
- **CHANGELOG.md**: Must document breaking build changes
|
||||
|
||||
### With Testing
|
||||
|
||||
- **Pre-commit**: Run basic build validation
|
||||
|
||||
- **CI/CD**: Full platform build testing
|
||||
|
||||
- **Manual Testing**: Human verification of critical paths
|
||||
|
||||
## Competence Hooks
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Prevents Build Failures**: Catches issues before they reach production
|
||||
|
||||
- **Maintains Consistency**: Ensures all platforms build identically
|
||||
|
||||
- **Reduces Debugging Time**: Prevents build system regressions
|
||||
|
||||
### Common Pitfalls
|
||||
|
||||
- **Silent Failures**: Changes that work on one platform but break others
|
||||
|
||||
- **Dependency Conflicts**: Updates that create version incompatibilities
|
||||
|
||||
- **Documentation Drift**: Build scripts that don't match documentation
|
||||
|
||||
### Next Skill Unlock
|
||||
|
||||
- Learn to test build changes across all platforms simultaneously
|
||||
|
||||
### Teach-back
|
||||
|
||||
- "What three platforms must I test before committing a build script change?"
|
||||
|
||||
## Collaboration Hooks
|
||||
|
||||
### Team Review Requirements
|
||||
|
||||
- **Platform Owners**: iOS, Android, Electron, Web specialists
|
||||
|
||||
- **DevOps**: CI/CD pipeline maintainers
|
||||
|
||||
- **QA**: Testing infrastructure owners
|
||||
|
||||
### Discussion Prompts
|
||||
|
||||
- "Which platforms will be affected by this build change?"
|
||||
|
||||
- "How can we test this change without breaking existing builds?"
|
||||
|
||||
- "What's our rollback plan if this change fails?"
|
||||
|
||||
## Self-Check (Before Allowing Changes)
|
||||
|
||||
- [ ] **Authorization Level**: Is this change appropriate for the level?
|
||||
|
||||
- [ ] **Testing Plan**: Is there a comprehensive testing strategy?
|
||||
|
||||
- [ ] **Documentation**: Will BUILDING.md be updated?
|
||||
|
||||
- [ ] **Rollback**: Is there a safe rollback mechanism?
|
||||
|
||||
- [ ] **Team Review**: Have appropriate stakeholders been consulted?
|
||||
|
||||
- [ ] **CI/CD**: Will this pass the build pipeline?
|
||||
|
||||
## Continuous Improvement & Feedback
|
||||
|
||||
### Feedback Collection
|
||||
|
||||
The Build Architecture Guard system includes feedback mechanisms to continuously
|
||||
improve its effectiveness:
|
||||
|
||||
- **User Feedback**: Script includes feedback prompts for guard improvements
|
||||
|
||||
- **Pattern Analysis**:
|
||||
|
||||
Monitor which file patterns trigger false positives/negatives
|
||||
|
||||
- **Documentation Gaps**: Track which changes lack proper documentation
|
||||
|
||||
- **Testing Effectiveness**: Measure how often guard catches actual issues
|
||||
|
||||
### Feedback Integration Process
|
||||
|
||||
1. **Collect Feedback**: Monitor guard execution logs and user reports
|
||||
|
||||
2. **Analyze Patterns**: Identify common false positives or missed patterns
|
||||
|
||||
3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
|
||||
|
||||
4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
|
||||
|
||||
5. **Test Changes**: Verify guard improvements don't introduce new issues
|
||||
|
||||
6. **Document Updates**: Update guard documentation with new patterns
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **False Positives**: Files flagged as sensitive that shouldn't be
|
||||
|
||||
- **False Negatives**: Sensitive files that weren't caught
|
||||
|
||||
- **Missing Patterns**: New file types that should be protected
|
||||
|
||||
- **Overly Strict**: Patterns that are too restrictive
|
||||
|
||||
- **Documentation Gaps**: Missing guidance for specific change types
|
||||
|
||||
- **Testing Improvements**: Better validation procedures
|
||||
|
||||
### Feedback Reporting
|
||||
|
||||
When reporting guard issues, include:
|
||||
|
||||
- **File patterns** that triggered false positives/negatives
|
||||
|
||||
- **Build system changes** that weren't properly caught
|
||||
|
||||
- **Documentation gaps** in current guard rules
|
||||
|
||||
- **Testing procedures** that could be improved
|
||||
|
||||
- **User experience** issues with guard enforcement
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/architecture/build_architecture_guard.mdc` for
|
||||
|
||||
core protection guidelines
|
||||
|
||||
- `.cursor/rules/architecture/build_validation.mdc` for validation procedures
|
||||
|
||||
**Status**: Active testing requirements
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: build_architecture_guard.mdc, build_validation.mdc
|
||||
**Stakeholders**: Development team, DevOps team, Build team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Build Testing
|
||||
|
||||
- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes
|
||||
- [ ] **Platform Coverage**: Identify all platforms that need testing
|
||||
- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies
|
||||
- [ ] **Resource Planning**: Plan testing resources and time requirements
|
||||
|
||||
### During Build Testing
|
||||
|
||||
- [ ] **Test Execution**: Execute planned tests across all platforms
|
||||
- [ ] **Issue Tracking**: Track and document any issues found
|
||||
- [ ] **Feedback Collection**: Collect feedback on testing effectiveness
|
||||
- [ ] **Documentation**: Document testing procedures and results
|
||||
|
||||
### After Build Testing
|
||||
|
||||
- [ ] **Result Analysis**: Analyze testing results and identify patterns
|
||||
- [ ] **Feedback Integration**: Integrate feedback into testing procedures
|
||||
- [ ] **Process Improvement**: Update testing procedures based on feedback
|
||||
- [ ] **Team Communication**: Share testing results and improvements with team
|
||||
Reference in New Issue
Block a user