Migrating Guide: v2.0.0-pre13

This version introduces the Feature Autoloading System for automatic discovery and loading of feature-specific configuration files, enabling cleaner separation between core model definitions and feature configurations.

Feature Autoloading System

What Changed

Features now automatically discover and load extension files from your project directories using conventional file naming patterns. This eliminates the need to configure features in your main model files.

Basic Migration

Before

# app/models/user.rb
class User < Familia::Horreum
  field :name, :email, :password

  feature :safe_dump
  safe_dump_fields :name, :email  # Configuration mixed with model
end

After

# app/models/user.rb - Clean model definition
class User < Familia::Horreum
  field :name, :email, :password
  feature :safe_dump  # Configuration auto-loaded
end

# app/models/user/safe_dump_extensions.rb - Automatically discovered
class User
  safe_dump_fields :name, :email
end

File Naming Convention

Extension files follow the pattern: {model_name}/{feature_name}_*.rb

app/models/
├── user.rb
├── user/
│   ├── safe_dump_extensions.rb    # SafeDump configuration
│   └── expiration_config.rb       # Expiration settings

Migration Steps

  1. Create extension directories: mkdir -p app/models/user
  2. Extract feature configuration from main model files to separate extension files
  3. Verify autoloading: Check that feature methods are available after migration

Debugging

Enable debug output to troubleshoot autoloading:

ENV['FAMILIA_DEBUG'] = '1'  # Shows discovered and loaded files

Common issues:

  • Files must follow {feature_name}_*.rb naming pattern
  • Extension files should reopen the same class as your model

Architecture

The Feature Autoloading System consists of two key components:

Familia::Features::Autoloader

A utility module providing shared file loading functionality:

  • Handles Dir.glob pattern matching and file loading
  • Provides consistent debug logging across all autoloading scenarios
  • Used by both feature-specific and general-purpose autoloading

Familia::Features::Autoloadable

A mixin for feature modules that enables post-inclusion autoloading:

  • Uses Module.const_source_location to find where user classes are defined
  • Discovers extension files using conventional patterns relative to the user class location
  • Integrates with the feature system's inclusion lifecycle

When you call feature :safe_dump, the SafeDump module (which includes Autoloadable) triggers post-inclusion autoloading that searches for user/safe_dump_*.rb files and loads them automatically.

New Capabilities

  1. Automatic Extension Discovery: No manual require statements needed
  2. Conventional File Organization: Standard patterns for consistent project structure
  3. Feature Isolation: Clean separation between core models and feature configurations
  4. Shared Autoloader Infrastructure: Consistent loading behavior across all features
  5. Debug Support: Built-in debugging for troubleshooting autoloading issues

Breaking Changes

None - This release is fully backward compatible. Existing models and feature configurations continue to work without modification.