~/wiki
Récent+ Ajouter

Legacy Archival Patterns

Confiance : high
legacy-archivalcode-migrationtechnical-debtarchive-managementcodebase-simplificationknowledge-preservationclean-architecture

Systematic approach to preserving deprecated code while simplifying active codebases. Balances the need for clean, maintainable systems with the requirement to preserve historical context and enable rollback capabilities.

Core Philosophy

Legacy code often contains valuable domain knowledge, edge case handling, and business logic that cannot be easily recreated. Rather than deleting this knowledge, archival patterns preserve it in a structured way that doesn't interfere with active development.

Archival Strategies

Directory-Based Archival

Move deprecated modules to clearly marked archive directories:

src/
├── active_module/          # Current production code
├── _archive/              # Archived implementations
│   ├── v1_legacy/         # Original implementation
│   ├── v2_experimental/   # Failed experiment
│   └── v3_complex/        # Over-engineered version
└── README.md              # Archive documentation

Documentation Preservation

Maintain comprehensive documentation about archived decisions:

  • Archival Reasons: Why the code was deprecated
  • Historical Context: Original requirements and constraints
  • Migration Notes: What was learned during migration
  • Rollback Procedures: How to restore functionality if needed

Knowledge Transfer

Extract valuable patterns and lessons from legacy code:

  • Document architectural decisions and their outcomes
  • Preserve domain-specific business logic
  • Maintain test cases that validate core functionality
  • Create migration guides for future reference

Implementation Guidelines

Pre-Archival Assessment

Before archiving code, evaluate:

  1. Business Logic: Extract reusable domain knowledge
  2. Edge Cases: Document unusual scenarios handled by legacy code
  3. Performance Optimizations: Preserve optimization techniques
  4. Integration Points: Document external system interactions

Archival Process

  1. Create Archive Directory: Establish clear organizational structure
  2. Move Code: Relocate deprecated modules with full history
  3. Update Dependencies: Ensure no active code references archived modules
  4. Document Decision: Create comprehensive archival documentation
  5. Validate Removal: Confirm system functions without archived components

Post-Archival Maintenance

  • Periodic Review: Assess whether archived code can be permanently deleted
  • Knowledge Extraction: Continue mining archived code for useful patterns
  • Rollback Planning: Maintain procedures for restoring archived functionality

Real-World Example: Assistant-RH Migration

The assistant-rh project implemented comprehensive legacy archival during its V3 Clean migration:

Archival Structure

src/
├── rag_v3_clean/          # New autonomous module
├── _archive/              # Legacy preservation
│   ├── rag/              # Original implementation
│   ├── rag_v2/           # Production version
│   └── rag_v3/           # Complex experimental version
└── ARCHIVE.md             # Migration documentation

Preserved Knowledge

  • Multi-Source RAG Patterns: Complex retrieval coordination logic
  • Fault Tolerance Mechanisms: Error handling and graceful degradation
  • Performance Optimizations: Caching and embedding strategies
  • Domain Logic: French legal document processing specifics

Migration Benefits

  • Simplified Codebase: 53% reduction in active code
  • Preserved Context: Full historical implementation available
  • Rollback Capability: Ability to restore any previous version
  • Knowledge Retention: Domain expertise preserved for future engineers

Benefits

For Current Development

  • Reduced Complexity: Cleaner codebase without losing institutional knowledge
  • Faster Onboarding: New developers can focus on active code
  • Simplified Testing: Fewer code paths to validate
  • Improved Performance: Elimination of deprecated code paths

For Future Maintenance

  • Historical Reference: Understanding of previous approaches and their limitations
  • Rollback Options: Ability to restore functionality if new implementations fail
  • Knowledge Mining: Source of patterns and solutions for future challenges
  • Audit Trail: Complete history of architectural decisions and their outcomes

Anti-Patterns to Avoid

Incomplete Archival

  • Partial Migration: Leaving dependencies to archived code in active system
  • Missing Documentation: Archiving without explaining why or how
  • Reference Cleanup: Failing to update imports and dependencies

Over-Archival

  • Premature Archival: Moving code that's still being actively maintained
  • Excessive Preservation: Keeping every minor variation and experiment
  • Documentation Overhead: Creating more documentation than the archived code is worth

Integration with Development Workflow

Version Control Integration

  • Use git branches or tags to mark archival points
  • Maintain clear commit messages explaining archival decisions
  • Consider using git submodules for large archived components

CI/CD Considerations

  • Exclude archived directories from build processes
  • Maintain separate test suites for archived components
  • Document deployment procedures for rollback scenarios

Team Communication

  • Announce archival decisions to development team
  • Provide training on accessing and understanding archived code
  • Establish procedures for when to consult archived implementations

See also