Rustelo/book/reference/feature-migration.md

Feature Migration Guide

This guide covers how to migrate features between different versions of Rustelo and how to add or remove features from your configuration.

Overview

Feature migrations may be necessary when:

• Upgrading to a new version of Rustelo
• Adding new features to your application
• Removing unused features
• Changing feature configurations
• Moving between environments with different feature sets

Migration Process

1. Backup Current Configuration

Always backup your current configuration before migrating:

./config/scripts/manage-config.sh backup prod
./config/scripts/manage-config.sh backup dev

2. Assess Current Features

List currently enabled features:

./config/scripts/debug-manage.sh list-features
./config/scripts/debug-manage.sh status

3. Plan Feature Changes

Document the changes needed:

• Features to enable
• Features to disable
• Feature configurations to update
• Dependencies to consider

4. Update Feature Configurations

Update individual feature configurations as needed.

5. Rebuild Configurations

Rebuild configurations for all environments:

./config/scripts/build-config.sh dev
./config/scripts/build-config.sh prod config.prod.toml
./config/scripts/build-config.sh example config.example.toml

6. Validate Changes

Validate the new configuration:

./config/scripts/debug-manage.sh test

Feature Dependencies

Some features depend on others. The system handles these dependencies automatically:

Core Dependencies

• RBAC requires Authentication
• Content Management requires Authentication
• Advanced Email may require Authentication for user-specific templates

Optional Dependencies

• Metrics can integrate with any enabled feature
• TLS enhances security for all features
• Caching can improve performance for any feature

Adding New Features

Step 1: Create Feature Configuration

Use the template command to create a new feature:

./config/scripts/debug-manage.sh template my_new_feature

This creates:

• config/features/my_new_feature/dev.toml
• config/features/my_new_feature/prod.toml
• config/features/my_new_feature/example.toml
• config/features/my_new_feature/README.md

Step 2: Configure Feature Settings

Edit each environment file with appropriate settings:

# config/features/my_new_feature/dev.toml
[features]
my_new_feature = true

[my_new_feature]
enabled = true
debug_mode = true
# Development-specific settings

# config/features/my_new_feature/prod.toml
[features]
my_new_feature = true

[my_new_feature]
enabled = true
debug_mode = false
# Production-specific settings

Step 3: Update Documentation

Document your new feature:

• Update feature README
• Add to main documentation
• Update migration guides

Step 4: Test Feature

Test the feature in all environments:

# Test development
./config/scripts/build-config.sh dev config.test.toml
# Test production
./config/scripts/build-config.sh prod config.test-prod.toml

Removing Features

Step 1: Assess Dependencies

Check if other features depend on the feature you want to remove:

# Review feature dependencies in documentation
grep -r "my_feature" config/features/

Step 2: Disable Feature

Set the feature to disabled in all environments:

[features]
my_feature = false

[my_feature]
enabled = false

Step 3: Remove Configuration Files (Optional)

If permanently removing:

rm -rf config/features/my_feature/

Step 4: Update Dependencies

Update any features that depended on the removed feature.

Feature Configuration Updates

Updating Existing Features

When updating feature configurations:

1. Review Changes: Understand what's changing and why
2. Update Gradually: Start with development, then staging, then production
3. Test Thoroughly: Ensure the feature still works as expected
4. Monitor Impact: Watch for performance or functionality changes

Example: Updating Authentication Feature

# Before
[auth.password]
min_length = 8
require_special_chars = false

# After
[auth.password]
min_length = 12
require_special_chars = true
require_uppercase = true
require_lowercase = true

Environment-Specific Feature Management

Development Environment

Development typically enables more features for testing:

[features]
auth = true
content = true
email = true
metrics = true
tls = false          # Not needed in development
rbac = true          # For testing
cache = true
debug_features = true # Development-only features

Production Environment

Production focuses on essential, stable features:

[features]
auth = true
content = true
email = true
metrics = true
tls = true           # Required for production
rbac = true
cache = true
debug_features = false # Disabled in production

Feature Flag Management

Runtime Feature Flags

Some features can be toggled at runtime:

[feature_flags]
auth_enabled = true
content_enabled = true
email_enabled = true
metrics_enabled = true

Conditional Features

Features can be conditionally enabled:

[feature_flags.conditional]
oauth_enabled = false        # Enable OAuth (requires auth)
two_factor_enabled = true   # Enable 2FA (requires auth)
file_uploads_enabled = true # Enable file uploads (requires content)

Migration Scripts

Automated Feature Migration

Create scripts for common migrations:

#!/bin/bash
# migrate-to-v2.sh

# Update authentication feature
sed -i 's/min_length = 8/min_length = 12/' config/features/auth/*.toml

# Enable new security features
echo "csrf_protection = true" >> config/features/auth/prod.toml

# Rebuild configurations
./config/scripts/build-config.sh prod config.prod.toml

Feature Validation Script

#!/bin/bash
# validate-features.sh

echo "Validating feature configurations..."

for env in dev prod example; do
    echo "Testing $env environment..."
    if ./config/scripts/build-config.sh "$env" "test_$env.toml"; then
        echo "✓ $env configuration valid"
        rm "test_$env.toml"
    else
        echo "✗ $env configuration invalid"
        exit 1
    fi
done

echo "All feature configurations valid!"

Rollback Procedures

Feature Rollback

If a feature migration fails:

1. Disable the Feature:

   [features]
   problematic_feature = false
   

2. Restore Previous Configuration:

   ./config/scripts/manage-config.sh restore backup_file.toml
   

3. Rebuild and Deploy:

   ./config/scripts/build-config.sh prod config.prod.toml
   

Partial Rollback

Roll back specific feature settings:

# Restore specific feature from backup
cp backup/features/auth/prod.toml config/features/auth/prod.toml

# Rebuild configuration
./config/scripts/build-config.sh prod config.prod.toml

Testing Feature Migrations

Unit Testing

Test individual feature configurations:

# Test feature configuration loading
cargo test feature_config_tests

# Test feature initialization
cargo test feature_init_tests

Integration Testing

Test feature interactions:

# Test feature dependencies
cargo test feature_dependency_tests

# Test feature combinations
cargo test feature_integration_tests

End-to-End Testing

Test complete feature workflows:

# Test authentication flow
cargo test auth_e2e_tests

# Test content management flow
cargo test content_e2e_tests

Monitoring Feature Changes

Feature Usage Metrics

Monitor feature usage after migration:

[metrics.features]
track_feature_usage = true
track_feature_performance = true
track_feature_errors = true

Health Checks

Add health checks for new features:

[health.features]
check_auth_status = true
check_email_connectivity = true
check_database_features = true

Best Practices

Planning

• Always plan feature changes in advance
• Consider impact on users and system performance
• Test changes in non-production environments first

Documentation

• Document all feature changes
• Update user guides and API documentation
• Maintain feature compatibility matrices

Communication

• Communicate feature changes to stakeholders
• Provide migration guides for users
• Announce deprecations well in advance

Monitoring

• Monitor feature performance after changes
• Track error rates and user feedback
• Be prepared to rollback if necessary

Troubleshooting

Common Issues

1. Feature Dependencies Not Met

   # Check feature dependencies
   grep -r "requires.*auth" config/features/
   

2. Configuration Conflicts

   # Validate configuration
   ./config/scripts/debug-manage.sh test
   

3. Feature Not Loading

   # Check feature flag
   grep "my_feature.*=.*true" config.toml
   

Debug Commands

# List enabled features
./config/scripts/debug-manage.sh list-features

# Show feature status
./config/scripts/debug-manage.sh status

# Test specific feature
./config/scripts/build-config.sh dev --feature=my_feature

Getting Help

For feature migration assistance:

• Review the Features Configuration Guide
• Check the Troubleshooting Guide
• Consult feature-specific documentation
• Contact technical support

Migration Checklist

• Backup current configurations
• Document planned changes
• Check feature dependencies
• Update feature configurations
• Test in development environment
• Validate in staging environment
• Deploy to production
• Monitor feature performance
• Update documentation
• Train team on changes