156 lines
5.1 KiB
Markdown
156 lines
5.1 KiB
Markdown
# Log-Free Codebase Policy
|
|
|
|
## Overview
|
|
|
|
The Project Mycelium maintains a **log-free codebase** in main and development branches as a core architectural design decision. This policy ensures clean, production-ready code and simplifies maintenance, debugging, and AI-assisted development.
|
|
|
|
## Policy Statement
|
|
|
|
**All `log::` statements must be removed from the codebase before merging to main or development branches.**
|
|
|
|
## Rationale
|
|
|
|
### 1. **Code Cleanliness**
|
|
- Removes visual clutter and noise from the codebase
|
|
- Improves code readability and maintainability
|
|
- Reduces file size and complexity
|
|
|
|
### 2. **Production Readiness**
|
|
- Eliminates potential performance overhead from logging statements
|
|
- Prevents accidental logging of sensitive information
|
|
- Ensures consistent behavior across environments
|
|
|
|
### 3. **AI-Assisted Development**
|
|
- Simplifies code analysis and pattern recognition for AI tools
|
|
- Reduces token count and complexity for AI code generation
|
|
- Enables more accurate code migrations and refactoring
|
|
|
|
### 4. **Maintenance Benefits**
|
|
- Reduces merge conflicts from logging changes
|
|
- Eliminates outdated or inconsistent log messages
|
|
- Simplifies code review process
|
|
|
|
## Implementation Guidelines
|
|
|
|
### ✅ **Allowed Usage**
|
|
- **Feature Branches**: Developers may use `log::` statements for troubleshooting and debugging in feature branches
|
|
- **Local Development**: Temporary logging for development and testing purposes
|
|
- **Debugging Sessions**: Short-term logging to diagnose specific issues
|
|
|
|
### ❌ **Prohibited Usage**
|
|
- **Main Branch**: No `log::` statements allowed in main branch
|
|
- **Development Branch**: No `log::` statements allowed in development branch
|
|
- **Production Code**: No logging statements in production-ready code
|
|
- **Permanent Logging**: No long-term or permanent logging infrastructure
|
|
|
|
## Enforcement
|
|
|
|
### 1. **Pre-Merge Cleanup**
|
|
All feature branches must have `log::` statements removed before creating pull requests:
|
|
|
|
```bash
|
|
# Check for log statements before merging
|
|
find src -name "*.rs" -exec grep -l "log::" {} \;
|
|
|
|
# Remove all log statements (if any found)
|
|
find src -name "*.rs" -exec perl -i -pe 'BEGIN{undef $/;} s/\s*log::[^;]*;//g' {} \;
|
|
|
|
# Verify removal
|
|
cargo check --lib
|
|
```
|
|
|
|
### 2. **Automated Checks**
|
|
- CI/CD pipeline should include log statement detection
|
|
- Pre-commit hooks can prevent accidental commits with logging
|
|
- Code review checklist includes log statement verification
|
|
|
|
### 3. **Migration History**
|
|
- **2025-01-06**: Removed 881+ log statements from entire codebase
|
|
- **Dashboard Controller**: 443 log statements removed
|
|
- **Other Controllers**: 438 log statements removed across 24 files
|
|
|
|
## Alternative Approaches
|
|
|
|
### For Debugging
|
|
Instead of permanent logging, use:
|
|
|
|
1. **Conditional Compilation**:
|
|
```rust
|
|
#[cfg(debug_assertions)]
|
|
eprintln!("Debug: {}", value);
|
|
```
|
|
|
|
2. **Feature Flags**:
|
|
```rust
|
|
#[cfg(feature = "debug-logging")]
|
|
log::debug!("Debug information");
|
|
```
|
|
|
|
3. **Test-Only Logging**:
|
|
```rust
|
|
#[cfg(test)]
|
|
println!("Test debug: {}", value);
|
|
```
|
|
|
|
### For Production Monitoring
|
|
- Use external monitoring tools (Prometheus, Grafana)
|
|
- Implement structured error handling with Result types
|
|
- Use application metrics instead of log statements
|
|
- Implement health check endpoints
|
|
|
|
## Benefits Realized
|
|
|
|
### 1. **Codebase Statistics**
|
|
- **Before**: 881+ log statements across 24 files
|
|
- **After**: 0 log statements (100% reduction)
|
|
- **Compilation**: Clean builds with only minor unused variable warnings
|
|
|
|
### 2. **Development Improvements**
|
|
- Simplified ResponseBuilder migration process
|
|
- Reduced code complexity for AI-assisted refactoring
|
|
- Cleaner code reviews and merge processes
|
|
- Improved code readability and maintainability
|
|
|
|
### 3. **Performance Benefits**
|
|
- Reduced binary size
|
|
- Eliminated runtime logging overhead
|
|
- Faster compilation times
|
|
- Cleaner production deployments
|
|
|
|
## Compliance
|
|
|
|
### Developer Responsibilities
|
|
1. **Remove all `log::` statements** before creating pull requests
|
|
2. **Verify clean builds** after log removal
|
|
3. **Use alternative debugging approaches** for troubleshooting
|
|
4. **Follow the log-free policy** consistently across all contributions
|
|
|
|
### Code Review Requirements
|
|
1. **Check for log statements** in all code reviews
|
|
2. **Verify compilation** after any log-related changes
|
|
3. **Ensure policy compliance** before approving merges
|
|
4. **Document any exceptions** (if absolutely necessary)
|
|
|
|
## Exceptions
|
|
|
|
**No exceptions are currently allowed.** The log-free policy is absolute for main and development branches.
|
|
|
|
If logging becomes absolutely necessary for specific use cases, it must be:
|
|
1. Approved by the architecture team
|
|
2. Implemented with feature flags
|
|
3. Documented as an architectural decision
|
|
4. Reviewed regularly for removal
|
|
|
|
## Related Documentation
|
|
|
|
- [Builder Pattern Architecture](./builder-pattern-architecture.md)
|
|
- [ResponseBuilder Migration Guide](./response-builder-migration.md)
|
|
- [Code Quality Standards](./code-quality-standards.md)
|
|
- [AI-Assisted Development Guidelines](./ai-development-guidelines.md)
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-06
|
|
**Policy Version**: 1.0
|
|
**Status**: Active and Enforced
|