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:

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

### 2. Assess Current Features

List currently enabled features:

```bash
./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:

```bash
./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:

```bash
./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:

```bash
./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:

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

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

```toml
# 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:

```bash
# 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:

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

### Step 2: Disable Feature

Set the feature to disabled in all environments:

```toml
[features]
my_feature = false

[my_feature]
enabled = false
```

### Step 3: Remove Configuration Files (Optional)

If permanently removing:

```bash
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

```toml
# 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:

```toml
[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:

```toml
[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:

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

### Conditional Features

Features can be conditionally enabled:

```toml
[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:

```bash
#!/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

```bash
#!/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**:
   ```toml
   [features]
   problematic_feature = false
   ```

2. **Restore Previous Configuration**:
   ```bash
   ./config/scripts/manage-config.sh restore backup_file.toml
   ```

3. **Rebuild and Deploy**:
   ```bash
   ./config/scripts/build-config.sh prod config.prod.toml
   ```

### Partial Rollback

Roll back specific feature settings:

```bash
# 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:

```bash
# Test feature configuration loading
cargo test feature_config_tests

# Test feature initialization
cargo test feature_init_tests
```

### Integration Testing

Test feature interactions:

```bash
# Test feature dependencies
cargo test feature_dependency_tests

# Test feature combinations
cargo test feature_integration_tests
```

### End-to-End Testing

Test complete feature workflows:

```bash
# 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:

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

### Health Checks

Add health checks for new features:

```toml
[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**
   ```bash
   # Check feature dependencies
   grep -r "requires.*auth" config/features/
   ```

2. **Configuration Conflicts**
   ```bash
   # Validate configuration
   ./config/scripts/debug-manage.sh test
   ```

3. **Feature Not Loading**
   ```bash
   # Check feature flag
   grep "my_feature.*=.*true" config.toml
   ```

### Debug Commands

```bash
# 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](../configuration/features.md)
- Check the [Troubleshooting Guide](../troubleshooting/common.md)
- 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