0d0297423e
Some checks failed
CI/CD Pipeline / Test Suite (push) Has been cancelled
CI/CD Pipeline / Security Audit (push) Has been cancelled
CI/CD Pipeline / Performance Benchmarks (push) Has been cancelled
Rust CI / Security Audit (push) Has been cancelled
Rust CI / Check + Test + Lint (nightly) (push) Has been cancelled
Rust CI / Check + Test + Lint (stable) (push) Has been cancelled
CI/CD Pipeline / Build Docker Image (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
CI/CD Pipeline / Cleanup (push) Has been cancelled
454 lines
14 KiB
Markdown
454 lines
14 KiB
Markdown
# Migration Guide - Unified Template Architecture
|
|
|
|
## 🎯 Overview
|
|
|
|
This guide helps you migrate from the previous template system to the new unified template architecture with layered override system. The new system provides:
|
|
|
|
- **Unified template management** across all project types
|
|
- **Layered override system** (Local > Feature > Template > Framework)
|
|
- **Framework integrity protection** for safe updates
|
|
- **Feature-aware tooling** that adapts to enabled features
|
|
- **Complete tooling integration** (just, CSS, configs, scripts)
|
|
|
|
## 🚀 Quick Migration (5 Minutes)
|
|
|
|
For most projects, migration is automatic:
|
|
|
|
```bash
|
|
# 1. Update to latest Rustelo version
|
|
cargo install rustelo-cli --git https://github.com/your-org/rustelo
|
|
|
|
# 2. Run automatic migration
|
|
cargo rustelo migrate --from-legacy --backup
|
|
|
|
# 3. Validate integrity
|
|
cargo rustelo integrity validate --detailed
|
|
|
|
# 4. Test your project
|
|
just dev
|
|
```
|
|
|
|
## 📋 Migration Checklist
|
|
|
|
### Before Migration
|
|
- [ ] **Backup your project**: `cp -r my-project my-project-backup`
|
|
- [ ] **Document customizations**: Note any custom templates or overrides
|
|
- [ ] **Check git status**: Ensure working directory is clean
|
|
- [ ] **Update Rustelo**: Install latest version with new CLI
|
|
|
|
### During Migration
|
|
- [ ] **Run migration tool**: `cargo rustelo migrate --interactive`
|
|
- [ ] **Review changes**: Check generated files and moved configurations
|
|
- [ ] **Update dependencies**: Run `cargo update` if needed
|
|
- [ ] **Test build**: Ensure project builds with `just build`
|
|
|
|
### After Migration
|
|
- [ ] **Validate integrity**: `cargo rustelo integrity validate`
|
|
- [ ] **Test functionality**: Verify all features work as expected
|
|
- [ ] **Update documentation**: Note any changes in project README
|
|
- [ ] **Commit changes**: Commit migrated project to version control
|
|
|
|
## 🔄 Specific Migration Scenarios
|
|
|
|
### Scenario 1: Basic Project (No Custom Templates)
|
|
|
|
**Before**: Standard Rustelo project with default templates
|
|
**After**: Uses unified template system automatically
|
|
|
|
```bash
|
|
# Migration is automatic
|
|
cargo rustelo migrate
|
|
```
|
|
|
|
**Changes**:
|
|
- Templates now resolved through layered system
|
|
- Configuration moved to `config/` directory structure
|
|
- Tooling commands available through layered justfile
|
|
|
|
### Scenario 2: Custom Templates in foundation/templates/
|
|
|
|
**Before**: Custom templates in `crates/foundation/templates/`
|
|
**After**: Templates moved to appropriate layer
|
|
|
|
```bash
|
|
# Interactive migration with template analysis
|
|
cargo rustelo migrate --interactive --analyze-templates
|
|
|
|
# Review suggested moves:
|
|
# foundation/templates/custom.html → config/local/templates/custom.html
|
|
# foundation/templates/build.rs → templates/shared/build.rs.template
|
|
```
|
|
|
|
**Manual Steps**:
|
|
1. Review template analysis report
|
|
2. Confirm template categorization (local vs shared)
|
|
3. Update template references in your code
|
|
|
|
### Scenario 3: Heavy Customization (Multiple Features)
|
|
|
|
**Before**: Extensively customized project with multiple features
|
|
**After**: Organized through layered override system
|
|
|
|
```bash
|
|
# Comprehensive migration with feature detection
|
|
cargo rustelo migrate --comprehensive --detect-features
|
|
|
|
# Features detected and organized:
|
|
# analytics/ → config/features/analytics/
|
|
# smart-build/ → config/features/smart-build/
|
|
# custom-routes/ → config/local/routes/
|
|
```
|
|
|
|
**Post-Migration Structure**:
|
|
```
|
|
my-project/
|
|
├── config/
|
|
│ ├── local/ # Your local overrides (highest precedence)
|
|
│ ├── features/ # Feature-specific configurations
|
|
│ └── templates/ # Base template configurations
|
|
├── src/ # Your application code
|
|
└── scripts/ # Organized automation scripts
|
|
```
|
|
|
|
### Scenario 4: Team Project with Multiple Developers
|
|
|
|
**Before**: Inconsistent template usage across team
|
|
**After**: Standardized layered system
|
|
|
|
```bash
|
|
# Team lead runs migration
|
|
cargo rustelo migrate --team-mode --create-shared-config
|
|
|
|
# Generates shared configuration for team
|
|
# Creates .rustelo/team-config.toml
|
|
# Updates .gitignore for proper sharing
|
|
```
|
|
|
|
**Team Benefits**:
|
|
- Consistent development environment
|
|
- Safe customization without breaking updates
|
|
- Clear separation of shared vs personal overrides
|
|
|
|
## 🛠️ New Workflows
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# 1. Start development with all enabled features
|
|
just dev-full
|
|
|
|
# 2. Make changes to components/content/config
|
|
# Changes are hot-reloaded automatically
|
|
|
|
# 3. Quality check before committing
|
|
just quality # Runs formatting, linting, tests, and integrity validation
|
|
|
|
# 4. Commit with automatic validation
|
|
git add . && git commit -m "Your changes"
|
|
# Pre-commit hook runs integrity validation automatically
|
|
```
|
|
|
|
### Feature Management Workflow
|
|
|
|
```bash
|
|
# Add new feature to project
|
|
cargo rustelo add analytics
|
|
|
|
# What happens:
|
|
# - Feature dependencies added to Cargo.toml
|
|
# - Feature templates installed to config/features/analytics/
|
|
# - Justfile updated with analytics commands
|
|
# - UnoCSS config extended with analytics styles
|
|
|
|
# Remove feature cleanly
|
|
cargo rustelo remove analytics
|
|
# Removes all feature-specific configurations safely
|
|
```
|
|
|
|
### Customization Workflow
|
|
|
|
```bash
|
|
# 1. Override a template locally (highest precedence)
|
|
cargo rustelo override template justfile
|
|
# Creates config/local/justfile with current content
|
|
# Edit this file - your changes will take precedence
|
|
|
|
# 2. Override component behavior
|
|
cargo rustelo override component NavBar
|
|
# Creates src/components/local/NavBar.rs
|
|
# Implement your custom navigation bar
|
|
|
|
# 3. Add local configuration
|
|
echo 'theme_color = "#ff6b6b"' >> config/local/app.toml
|
|
# Local config overrides feature and base configs
|
|
```
|
|
|
|
### Update Workflow
|
|
|
|
```bash
|
|
# 1. Check update safety
|
|
cargo rustelo integrity validate --target-version 0.2.0
|
|
|
|
# 2. Safe update (if validation passes)
|
|
cargo rustelo update --version 0.2.0
|
|
|
|
# 3. If validation fails, repair first
|
|
cargo rustelo integrity repair --auto
|
|
cargo rustelo integrity validate
|
|
cargo rustelo update --version 0.2.0
|
|
|
|
# 4. Verify after update
|
|
just test-all
|
|
```
|
|
|
|
## 🗂️ New Directory Structure
|
|
|
|
### Before Migration
|
|
```
|
|
my-project/
|
|
├── crates/
|
|
│ └── foundation/
|
|
│ └── templates/ # Custom templates (problematic)
|
|
├── src/
|
|
├── config/ # Some configs
|
|
└── scripts/ # Some scripts
|
|
```
|
|
|
|
### After Migration
|
|
```
|
|
my-project/
|
|
├── config/
|
|
│ ├── local/ # Local overrides (highest precedence)
|
|
│ │ ├── justfile # Custom commands
|
|
│ │ ├── app.toml # App-specific config
|
|
│ │ └── templates/ # Local template overrides
|
|
│ ├── features/ # Feature-specific configurations
|
|
│ │ ├── analytics/
|
|
│ │ │ ├── justfile # Analytics commands
|
|
│ │ │ ├── uno.config.ts # Analytics styles
|
|
│ │ │ └── package.json # Analytics dependencies
|
|
│ │ └── smart-build/
|
|
│ │ └── justfile # Smart build commands
|
|
│ └── templates/ # Base template configurations
|
|
├── src/
|
|
│ ├── components/
|
|
│ │ ├── local/ # Local component overrides
|
|
│ │ └── features/ # Feature-specific components
|
|
│ └── content/
|
|
├── scripts/ # Organized by category
|
|
│ ├── local/ # Local automation
|
|
│ ├── features/ # Feature-specific scripts
|
|
│ └── templates/ # Base scripts
|
|
└── templates/ # Project template files
|
|
└── shared/ # Shared templates for generation
|
|
```
|
|
|
|
## 🔧 CLI Command Changes
|
|
|
|
### Template Management
|
|
```bash
|
|
# OLD: No unified template management
|
|
# NEW: Comprehensive template system
|
|
|
|
cargo rustelo template list # List all available templates
|
|
cargo rustelo template show justfile # Show template content
|
|
cargo rustelo template customize justfile # Create local override
|
|
cargo rustelo template sync # Sync with latest templates
|
|
```
|
|
|
|
### Feature Management
|
|
```bash
|
|
# OLD: Manual feature configuration
|
|
# NEW: Integrated feature system
|
|
|
|
cargo rustelo features list # List available features
|
|
cargo rustelo features enabled # Show enabled features
|
|
cargo rustelo add analytics # Add feature with all configs
|
|
cargo rustelo remove smart-build # Remove feature cleanly
|
|
cargo rustelo features sync # Update feature configurations
|
|
```
|
|
|
|
### Override Management
|
|
```bash
|
|
# NEW: Layered override system
|
|
|
|
cargo rustelo list-overrides # Show active overrides
|
|
cargo rustelo override template justfile # Override template locally
|
|
cargo rustelo override component NavBar # Override component locally
|
|
cargo rustelo trace template justfile # Show resolution path
|
|
cargo rustelo remove-override template justfile # Remove local override
|
|
```
|
|
|
|
### Integrity Protection
|
|
```bash
|
|
# NEW: Framework integrity validation
|
|
|
|
cargo rustelo integrity validate # Check integrity
|
|
cargo rustelo integrity validate --detailed # Detailed validation report
|
|
cargo rustelo integrity repair # Auto-repair violations
|
|
cargo rustelo integrity init # Setup integrity protection
|
|
```
|
|
|
|
## 🚨 Common Issues and Solutions
|
|
|
|
### Issue 1: "Template not found" after migration
|
|
|
|
**Problem**: Old template references in code
|
|
**Solution**:
|
|
```bash
|
|
# Find old references
|
|
grep -r "foundation/templates" src/
|
|
# Update to use layered system
|
|
cargo rustelo trace template <template_name>
|
|
```
|
|
|
|
### Issue 2: Custom justfile commands missing
|
|
|
|
**Problem**: Commands defined in old locations
|
|
**Solution**:
|
|
```bash
|
|
# Create local override
|
|
cargo rustelo override template justfile
|
|
# Add your custom commands to config/local/justfile
|
|
```
|
|
|
|
### Issue 3: Integrity validation fails
|
|
|
|
**Problem**: Code violates framework boundaries
|
|
**Solution**:
|
|
```bash
|
|
# Get detailed violation report
|
|
cargo rustelo integrity validate --detailed
|
|
|
|
# Auto-repair common issues
|
|
cargo rustelo integrity repair
|
|
|
|
# Manual fixes for critical violations
|
|
# (Follow suggestions in validation report)
|
|
```
|
|
|
|
### Issue 4: Feature conflicts after migration
|
|
|
|
**Problem**: Multiple features providing conflicting configurations
|
|
**Solution**:
|
|
```bash
|
|
# Check feature status
|
|
cargo rustelo features status
|
|
|
|
# Resolve conflicts through local overrides
|
|
cargo rustelo override config <conflicting_config>
|
|
```
|
|
|
|
### Issue 5: Build performance regression
|
|
|
|
**Problem**: New layered system seems slower
|
|
**Solution**:
|
|
```bash
|
|
# Enable smart-build feature
|
|
cargo rustelo add smart-build
|
|
|
|
# Use cached builds
|
|
just build-cached
|
|
|
|
# Optimize cache
|
|
just cache-optimize
|
|
```
|
|
|
|
## 📊 Benefits Comparison
|
|
|
|
### Development Experience
|
|
|
|
| Aspect | Before | After |
|
|
|--------|---------|-------|
|
|
| Template Management | Manual files | Unified system with CLI |
|
|
| Feature Integration | Manual configuration | Automatic with `rustelo add` |
|
|
| Customization | Risky modifications | Safe layered overrides |
|
|
| Team Collaboration | Inconsistent setups | Standardized configurations |
|
|
| Framework Updates | Often broke customizations | Protected integrity system |
|
|
|
|
### Code Quality
|
|
|
|
| Aspect | Before | After |
|
|
|--------|---------|-------|
|
|
| Consistency | Manual enforcement | Automated validation |
|
|
| Documentation | Scattered | Centralized and generated |
|
|
| Testing | Project-specific | Integrated test patterns |
|
|
| Performance | Variable | Optimized with smart-build |
|
|
|
|
## 🎓 Learning Path
|
|
|
|
### Week 1: Basic Usage
|
|
- [ ] Complete migration checklist
|
|
- [ ] Learn new CLI commands (`rustelo --help`)
|
|
- [ ] Practice override system (`rustelo override --help`)
|
|
- [ ] Understand layered precedence (Local > Feature > Template > Framework)
|
|
|
|
### Week 2: Advanced Features
|
|
- [ ] Add your first feature (`rustelo add analytics`)
|
|
- [ ] Customize feature configuration
|
|
- [ ] Learn integrity validation (`rustelo integrity validate`)
|
|
- [ ] Practice safe update workflow
|
|
|
|
### Week 3: Team Integration
|
|
- [ ] Set up shared team configuration
|
|
- [ ] Document team-specific overrides
|
|
- [ ] Implement CI/CD with integrity checks
|
|
- [ ] Train team members on new workflows
|
|
|
|
### Month 2+: Mastery
|
|
- [ ] Create custom features
|
|
- [ ] Contribute to framework templates
|
|
- [ ] Optimize build performance with smart caching
|
|
- [ ] Help other teams migrate
|
|
|
|
## 💡 Tips and Best Practices
|
|
|
|
### Template Customization
|
|
- **DO**: Use local overrides for project-specific changes
|
|
- **DON'T**: Modify framework core files directly
|
|
- **TIP**: Use `cargo rustelo trace` to understand resolution
|
|
|
|
### Configuration Management
|
|
- **DO**: Keep sensitive config in environment variables
|
|
- **DON'T**: Commit secrets to configuration files
|
|
- **TIP**: Use `.env.example` for configuration templates
|
|
|
|
### Feature Integration
|
|
- **DO**: Add features through CLI for proper integration
|
|
- **DON'T**: Manually copy feature files
|
|
- **TIP**: Check feature compatibility before adding multiple features
|
|
|
|
### Update Safety
|
|
- **DO**: Run integrity validation before updates
|
|
- **DON'T**: Force updates when validation fails
|
|
- **TIP**: Use auto-repair for common violations
|
|
|
|
### Team Collaboration
|
|
- **DO**: Share feature configurations through version control
|
|
- **DON'T**: Share local overrides unless specifically needed
|
|
- **TIP**: Document team conventions in project README
|
|
|
|
## 📞 Getting Help
|
|
|
|
### Self-Service Resources
|
|
1. **CLI Help**: `cargo rustelo help <command>`
|
|
2. **Template Documentation**: `cargo rustelo template docs`
|
|
3. **Integrity Reports**: `cargo rustelo integrity validate --detailed`
|
|
4. **Feature Guide**: `cargo rustelo features docs`
|
|
|
|
### Community Support
|
|
1. **GitHub Issues**: Report bugs and request features
|
|
2. **Discussions**: Ask questions and share experiences
|
|
3. **Discord/Slack**: Real-time help from community
|
|
4. **Documentation**: Comprehensive guides and examples
|
|
|
|
### Professional Support
|
|
1. **Migration Assistance**: Paid migration support for complex projects
|
|
2. **Custom Features**: Development of organization-specific features
|
|
3. **Training**: Team training on new architecture
|
|
4. **Consulting**: Architecture review and optimization
|
|
|
|
---
|
|
|
|
**Remember**: Migration is designed to be safe and incremental. Start small, validate often, and don't hesitate to ask for help if you encounter issues.
|