Legacy Code Migration for Breenix

Systematically migrate features from legacy kernel and remove old code when parity is reached.

Purpose

Breenix is transitioning from a legacy kernel (src.legacy/) to a modern implementation (kernel/). This skill provides patterns for safely migrating features, verifying parity, and removing legacy code.

When to Use

• Feature migration: Porting legacy features to new kernel
• Parity verification: Confirming new implementation matches legacy behavior
• Legacy removal: Safely removing old code after feature completion
• Documentation updates: Keeping FEATURE_COMPARISON.md current
• Risk assessment: Evaluating what can be safely removed

Legacy Migration Principle (from CLAUDE.md)

When new implementation reaches parity:
1. Remove code from src.legacy/
2. Update FEATURE_COMPARISON.md
3. Include removal in same commit as feature completion

Key Point: Don't accumulate dead code. Remove legacy as soon as parity is reached.

Migration Workflow

Phase 1: Identify Feature for Migration

Review FEATURE_COMPARISON.md:

# See what's in legacy but not new
cat docs/planning/legacy-migration/FEATURE_COMPARISON.md | grep "❌"

# See what's partially implemented
cat docs/planning/legacy-migration/FEATURE_COMPARISON.md | grep "🚧"

Common patterns:

• ✅ Fully implemented (safe to remove if in both)
• 🚧 Partially implemented (needs work)
• ❌ Not implemented (needs migration or decision)
• 🔄 Different approach (verify equivalence)

Phase 2: Analyze Legacy Implementation

Locate the legacy code:

# Find legacy implementation
find src.legacy -name "*feature_name*"

# Search for specific functionality
grep -r "feature_function" src.legacy/

Understand the implementation:

1. What does it do? (API, behavior, edge cases)
2. Why does it exist? (requirements it satisfies)
3. How does it work? (algorithm, data structures)
4. What depends on it? (other modules, tests)

Extract key characteristics:

• Public API surface
• Critical behavior
• Edge case handling
• Error conditions
• Test coverage

Phase 3: Implement in New Kernel

Follow Breenix standards:

// 1. Add to appropriate module in kernel/src/
// 2. Use modern Rust patterns
// 3. Add #[cfg(feature = "testing")] for test code
// 4. Write comprehensive tests
// 5. Document with clear comments

Quality checklist:

• Matches legacy API (if public)
• Handles all edge cases
• Error handling implemented
• Tests written and passing
• Documentation complete
• No compiler warnings
• Clippy clean

Phase 4: Verify Parity

Functional equivalence:

# Run tests for the feature
cargo test feature_name

# Check behavior matches legacy
# (Compare outputs, test edge cases)

# Run full test suite
cargo test

API compatibility:

• If API is public: Must match exactly
• If internal: Can improve design
• Document any intentional differences

Behavioral parity checklist:

• Same inputs produce same outputs
• Edge cases handled identically
• Error conditions match
• Performance acceptable
• Integration with other subsystems works

Phase 5: Update Documentation

Update FEATURE_COMPARISON.md:

### Feature Category
| Feature | Legacy | New | Notes |
|---------|--------|-----|-------|
| Feature X | ~~✅ Full~~ (removed) | ✅ | Migrated in PR #123, legacy removed |

Patterns:

• Change legacy column to ~~✅ Full~~ (removed)
• Update new column to ✅
• Add note about migration PR
• Include date if significant

Document any differences:

## Implementation Differences

### Feature X
- **Legacy**: Used approach A
- **New**: Uses approach B (reason)
- **Rationale**: Cleaner design, better performance, etc.

Phase 6: Remove Legacy Code

In the SAME commit as feature completion:

# Remove the legacy files
git rm src.legacy/path/to/feature.rs

# Or if removing entire module
git rm -r src.legacy/module/

# Stage FEATURE_COMPARISON.md changes
git add docs/planning/legacy-migration/FEATURE_COMPARISON.md

# Commit together
git commit -m "Complete Feature X implementation and remove legacy

- Implement Feature X in kernel/src/module/feature.rs
- Full parity with legacy implementation
- Remove legacy code from src.legacy/
- Update FEATURE_COMPARISON.md

Tested with: cargo test feature_x
"

Critical: Legacy removal MUST be in the same commit to maintain atomicity.

Legacy Code Categories

1. Direct Migration

What: Feature can be ported directly with minimal changes

Example: VGA text mode removed after framebuffer complete

Process:

1. Understand legacy implementation
2. Port to new codebase
3. Test thoroughly
4. Remove legacy
5. Update docs

2. Reimplementation

What: New approach taken, but achieves same goals

Example: Timer system (different RTC implementation)

Process:

1. Identify requirements from legacy
2. Design new approach
3. Implement with modern patterns
4. Verify equivalent behavior
5. Remove legacy
6. Document differences

3. Obsolete Features

What: Feature no longer needed or superseded

Example: VGA text after framebuffer works

Process:

1. Verify feature truly obsolete
2. Check no dependencies
3. Remove from legacy
4. Update FEATURE_COMPARISON.md with rationale

4. Deferred Features

What: Features not yet needed in new kernel

Example: Network stack (not current priority)

Process:

1. Document decision to defer
2. Mark as ❌ in FEATURE_COMPARISON.md
3. Leave in legacy as reference
4. Add to future roadmap

Common Migration Patterns

Pattern: Device Driver

// Legacy: src.legacy/drivers/device_x.rs
// New: kernel/src/drivers/device_x.rs

// 1. Port driver structure
pub struct DeviceX {
    // ... fields
}

// 2. Port initialization
impl DeviceX {
    pub fn new() -> Self { ... }
}

// 3. Port public API
impl DeviceX {
    pub fn operation(&mut self) { ... }
}

// 4. Add tests
#[cfg(test)]
mod tests {
    #[test]
    fn test_device_x() { ... }
}

Pattern: System Call

// Legacy: src.legacy/syscall/handler.rs (mostly commented out)
// New: kernel/src/syscall/handler.rs (full implementation)

// 1. Define syscall number
pub const SYS_FEATURE: u64 = N;

// 2. Add to dispatcher
pub fn syscall_handler(num: u64, args: ...) {
    match num {
        SYS_FEATURE => sys_feature(args),
        // ...
    }
}

// 3. Implement handler
fn sys_feature(args: ...) -> u64 {
    // Implementation
}

// 4. Test from userspace
// userspace/tests/feature_test.rs

Pattern: Infrastructure

// Legacy: Multiple files implementing async
// New: Consolidated in kernel/src/task/

// 1. Analyze legacy architecture
// 2. Design improved structure
// 3. Implement with better patterns
// 4. Migrate tests
// 5. Document improvements

Risk Assessment

Before removing legacy code, assess:

High Risk (Don't Remove Yet)

• Features not yet implemented in new kernel
• Complex subsystems (network, filesystem)
• Code with unique algorithms or logic
• Reference implementations for future work

Medium Risk (Remove with Caution)

• Features with partial new implementation
• Code with subtle edge cases
• Infrastructure with many dependencies

Low Risk (Safe to Remove)

• Features fully implemented and tested
• Obsolete approaches (VGA text mode)
• Dead code (never called)
• Superseded implementations

Integration with Development

During Feature Development

# 1. Check if legacy has this feature
grep -r "feature_name" src.legacy/

# 2. If found, analyze it
less src.legacy/path/to/feature.rs

# 3. Implement in new kernel
# ... development work ...

# 4. Test thoroughly
cargo test feature_name

# 5. Remove legacy in same commit
git rm src.legacy/path/to/feature.rs

# 6. Update FEATURE_COMPARISON.md
# ... edit ...

# 7. Commit together
git commit -m "Implement feature_name and remove legacy"

PR Review Checklist

When reviewing PRs that claim feature parity:

• New implementation tested
• Legacy code removed
• FEATURE_COMPARISON.md updated
• All changes in one atomic commit
• No regression in related features
• Documentation complete

Current Migration Status

Based on FEATURE_COMPARISON.md (as of latest):

Completed Migrations:

• Memory management (frame allocator, paging, heap) ✅
• Async executor and task management ✅
• Timer system (PIT + RTC) ✅
• Keyboard driver ✅
• Serial output ✅
• Test infrastructure ✅
• Syscall infrastructure ✅
• Fork/exec system calls ✅

Not Yet Migrated:

• Network drivers (Intel E1000, RTL8139) ❌
• PCI bus support ❌
• Interrupt statistics tracking ❌
• Event system ❌

Different Approach:

• Print macros (log system vs direct print) 🔄
• Display (framebuffer vs VGA text) 🔄

Special Cases

When Legacy Has Better Implementation

Scenario: Legacy code is actually better designed

Action:

1. Port legacy approach to new kernel
2. Improve if possible
3. Remove legacy
4. Document that you used legacy as reference

When API Must Change

Scenario: Legacy API is poor, new needs different design

Action:

1. Design better API
2. Document differences in FEATURE_COMPARISON.md
3. Explain rationale in commit message
4. Remove legacy

When Uncertain

Scenario: Not sure if new implementation is equivalent

Action:

1. Write comprehensive tests
2. Compare outputs on same inputs
3. Ask for review
4. Document any known differences
5. Only remove legacy when confident

Best Practices

1. Remove in same commit: Legacy removal with feature completion
2. Update docs immediately: Don't accumulate documentation debt
3. Test thoroughly: Verify parity before removing legacy
4. Document differences: Explain any intentional changes
5. Keep reference: For complex features, document algorithm before removing
6. Atomic operations: Feature + removal + docs in one commit
7. Review carefully: PRs that remove legacy need extra scrutiny

Example Migration Session

# Identify target feature
cat docs/planning/legacy-migration/FEATURE_COMPARISON.md | grep "❌"

# Found: Event system not yet implemented

# Analyze legacy
less src.legacy/events/mod.rs
grep -r "Event" src.legacy/

# Implement in new kernel
# ... create kernel/src/events/mod.rs ...
# ... write tests ...

# Verify
cargo test events

# Remove legacy and update docs
git rm -r src.legacy/events/
# Edit FEATURE_COMPARISON.md

# Commit atomically
git add kernel/src/events/ tests/test_events.rs
git add docs/planning/legacy-migration/FEATURE_COMPARISON.md
git commit -m "Implement event system and remove legacy

- Add event system in kernel/src/events/
- Full parity with legacy implementation
- Enhanced with better error handling
- Remove src.legacy/events/
- Update FEATURE_COMPARISON.md

Tested with: cargo test events
All tests passing, no regressions.
"

Summary

Legacy code migration requires:

• Systematic analysis of legacy implementation
• Full parity verification with tests
• Atomic commits (feature + removal + docs)
• FEATURE_COMPARISON.md updates
• Risk assessment before removal
• Documentation of differences

The goal: Clean codebase with no dead code accumulation.