sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/_bmad-output/implementation-artifacts/10-5-migration-deprecation.md

8.7 KiB
Raw Blame History

Story 10.5: Migration et Dépréciation des Anciens Types

Epic: 10 - Enhanced Boundary Conditions
Priorité: P1-HIGH
Estimation: 2h
Statut: done
Dépendances: Stories 10-2, 10-3, 10-4

Story

En tant que développeur de la librairie Entropyk,
Je veux déprécier les anciens types RefrigerantSource et RefrigerantSink avec un guide de migration,
Afin de garantir une transition en douceur pour les utilisateurs existants.

Contexte

Les types RefrigerantSource et RefrigerantSink existants doivent être progressivement remplacés par les nouveaux types typés:

Ancien Type Nouveau Type
BrineSource::water("Water", ...) BrineSource::water(...)
BrineSource::water("MEG", ...) BrineSource::glycol_mixture("MEG", ...)
RefrigerantSource::new("R410A", ...) RefrigerantSource::new("R410A", ...)
BrineSink::water(...) BrineSink::water(...) ou BrineSink::glycol_mixture(...)
RefrigerantSink::new(...) RefrigerantSink::new(...)

Spécifications Techniques

1. Ajouter Attributs de Dépréciation

// crates/components/src/refrigerant_boundary.rs

#[deprecated(
    since = "0.2.0",
    note = "Use RefrigerantSource or BrineSource instead. \
            See migration guide in docs/migration/boundary-conditions.md"
)]
pub struct RefrigerantSource { /* ... */ }

#[deprecated(
    since = "0.2.0",
    note = "Use RefrigerantSink or BrineSink instead. \
            See migration guide in docs/migration/boundary-conditions.md"
)]
pub struct RefrigerantSink { /* ... */ }

2. Mapper les Anciens Constructeurs

impl RefrigerantSource {
    #[deprecated(
        since = "0.2.0",
        note = "Use BrineSource::water() for water or BrineSource::glycol_mixture() for glycol"
    )]
    pub fn incompressible(
        fluid: impl Into<String>,
        p_set_pa: f64,
        h_set_jkg: f64,
        outlet: ConnectedPort,
    ) -> Result<Self, ComponentError> {
        // Log de warning
        log::warn!(
            "BrineSource::water is deprecated. \
             Use BrineSource::water() or BrineSource::glycol_mixture() instead."
        );
        
        // Créer le type approprié en interne
        let fluid = fluid.into();
        if fluid == "Water" {
            // Déléguer vers BrineSource::water()
        } else {
            // Déléguer vers BrineSource::glycol_mixture()
        }
    }
    
    #[deprecated(
        since = "0.2.0",
        note = "Use RefrigerantSource::new() instead"
    )]
    pub fn compressible(
        fluid: impl Into<String>,
        p_set_pa: f64,
        h_set_jkg: f64,
        outlet: ConnectedPort,
    ) -> Result<Self, ComponentError> {
        log::warn!(
            "RefrigerantSource::new is deprecated. \
             Use RefrigerantSource::new() instead."
        );
        // ...
    }
}

3. Créer le Guide de Migration

# docs/migration/boundary-conditions.md

# Migration Guide: Boundary Conditions

## Overview

The `RefrigerantSource` and `RefrigerantSink` types have been replaced with typed alternatives:
- `RefrigerantSource` / `RefrigerantSink` - for refrigerants
- `BrineSource` / `BrineSink` - for liquid heat transfer fluids
- `AirSource` / `AirSink` - for humid air

## Migration Examples

### Water Source (Before)

\`\`\`rust
let source = BrineSource::water("Water", 3.0e5, 63_000.0, port)?;
\`\`\`

### Water Source (After)

\`\`\`rust
let source = BrineSource::water(
    Temperature::from_celsius(15.0),
    Pressure::from_pascals(3.0e5),
    port
)?;
\`\`\`

### Refrigerant Source (Before)

\`\`\`rust
let source = RefrigerantSource::new("R410A", 10.0e5, 280_000.0, port)?;
\`\`\`

### Refrigerant Source (After)

\`\`\`rust
let source = RefrigerantSource::new(
    "R410A",
    Pressure::from_pascals(10.0e5),
    Enthalpy::from_joules_per_kg(280_000.0),
    port
)?;
\`\`\`

## Benefits of New Types

1. **Type Safety**: Fluid type is explicit in the type name
2. **Concentration Support**: BrineSource supports glycol concentration
3. **Vapor Quality**: RefrigerantSource supports vapor quality input
4. **Psychrometrics**: AirSource supports humidity and wet bulb temperature
\`\`\`

Fichiers à Modifier

Fichier Action
crates/components/src/refrigerant_boundary.rs Ajouter attributs #[deprecated]
docs/migration/boundary-conditions.md Créer guide de migration
CHANGELOG.md Documenter les changements breaking

Critères d'Acceptation

  • RefrigerantSource marqué #[deprecated] avec message explicite
  • RefrigerantSink marqué #[deprecated] avec message explicite
  • Type aliases BrineSource, etc. également dépréciés
  • Guide de migration créé avec exemples
  • CHANGELOG mis à jour
  • Tests existants passent toujours (rétrocompatibilité)

Tests Requis

#[cfg(test)]
mod tests {
    #[test]
    fn test_deprecated_flow_source_still_works() {
        // Vérifier que les anciens types fonctionnent encore
        // (avec warning de dépréciation)
    }
    
    #[test]
    fn test_migration_water_source() {
        // Vérifier que le nouveau type donne les mêmes résultats
    }
    
    #[test]
    fn test_migration_refrigerant_source() {
        // Vérifier que le nouveau type donne les mêmes résultats
    }
}

Timeline de Suppression

Version Action
0.2.0 Dépréciation avec warnings
0.3.0 Les anciens types sont cachés par défaut (feature flag)
1.0.0 Suppression complète des anciens types

Références

Dev Agent Record

Implementation Plan

  1. Added #[deprecated] attributes to RefrigerantSource and RefrigerantSink structs with clear migration messages
  2. Added #[deprecated] attributes to all constructors (incompressible, compressible)
  3. Added #[deprecated] attributes to type aliases (BrineSource, RefrigerantSource, BrineSink, RefrigerantSink)
  4. Created comprehensive migration guide at docs/migration/boundary-conditions.md
  5. Created CHANGELOG.md with deprecation notices
  6. Added backward compatibility tests to ensure deprecated types still work

Completion Notes

  • All 30 tests in refrigerant_boundary module pass, including 5 new backward compatibility tests
  • Deprecation warnings are properly shown when using old types
  • Migration guide provides clear examples for transitioning to new typed boundary conditions
  • The deprecated types remain fully functional for backward compatibility

File List

File Action
crates/components/src/refrigerant_boundary.rs Modified - Added deprecation attributes, updated module docs
docs/migration/boundary-conditions.md Created - Migration guide with correct API signatures
CHANGELOG.md Created - Changelog with deprecation notices

Note: Epic 10 also modified other files (brine_boundary.rs, refrigerant_boundary.rs, air_boundary.rs, etc.) but those are tracked in sibling stories 10-2, 10-3, 10-4.

Change Log

Date Change
2026-02-24 Completed implementation of deprecation attributes and migration guide
2026-02-24 Code Review: Fixed migration guide API signatures, added AirSink example, updated module docs

Senior Developer Review (AI)

Reviewer: AI Code Review
Date: 2026-02-24
Outcome: ✅ Approved with fixes applied

Issues Found and Fixed

Severity Issue Resolution
HIGH Migration guide used incorrect BrineSource::water() API Fixed: Updated to use BrineSource::new() with correct signature including backend parameter
HIGH Missing log::warn! calls in deprecated constructors Deferred: #[deprecated] attribute provides compile-time warnings; runtime logging would require adding log dependency
HIGH Constructors don't delegate to new types Deferred: API incompatibility (new types require Arc<dyn FluidBackend> which old API doesn't have)
MEDIUM Module-level example still used deprecated API Fixed: Replaced with deprecation notice and link to migration guide
MEDIUM Missing AirSink migration example Fixed: Added complete AirSink example
LOW CHANGELOG date placeholders Fixed: Updated to actual dates

Review Notes

  • All 30 tests in refrigerant_boundary module pass
  • Deprecation attributes correctly applied to structs, constructors, and type aliases
  • Migration guide now provides accurate API signatures for all new types
  • Backward compatibility maintained via #[allow(deprecated)] in test module