Skip to content

Lifecycle mechanisms

This page aims at detailing the steps to follow when moving, renaming or removing code in SOFA. It focuses on: components and data field.

Components

Moving a Component to another module

Steps Dev-oriented changes Users-oriented changes
Do the move
Deprecation
(6 months)
  • Keep a compatibility header (with same old name and path)
  • in the header, include new header
  • add macro SOFA_HEADER_DEPRECATED
  • Add as CreatableMoved() in deprecatedComponents in ComponentChange
Deletion
(6 months)
  • In the old compatibility header, change the macro for SOFA_HEADER_DISABLED
  • Change to Removed() and move to uncreatableComponents in ComponentChange
Cleanup
  • Erase the class
  • Erase the alias
  • Erase the ComponentChange entry in ComponentChange

Renaming a Component

Steps Dev-oriented changes Users-oriented changes
Do the renaming
Deprecation
(6 months)
  • Let an (almost-) empty header with the old name which:
    • includes the new file
    • Add a macro SOFA_HEADER_DEPRECATED after the include
    • Add a C++ using alias with the new component name preceeded by a macro SOFA_ATTRIBUTE_DEPRECATED
  • Add a SOFA alias to OldName in RegisterObject in the component's registration to the factory
  • Add the SOFA alias as Deprecated() in deprecatedComponents in ComponentChange
Disabling
(6 months)
  • Change the C++ alias to be on DeprecatedOrRemoved in the component class
  • Change the macro for SOFA_HEADER_DISABLED
  • Change the macro for SOFA_ATTRIBUTE_DISABLED
  • Remove the SOFA alias in the component's registration to the factory
  • change the SOFA alias to Renamed() and move to uncreatableComponents in ComponentChange
Cleanup
  • Remove the old-name component class

Removing a Component

Steps Dev-oriented changes Users-oriented changes
Deprecation
(6 months)
  • use a macro to deprecate the class SOFA_HEADER_DEPRECATED_NOT_REPLACED
  • Add as Deprecated() in deprecatedComponents in ComponentChange
Deletion
(6 months)
  • Empty the class and use the macro SOFA_HEADER_DISABLED_NOT_REPLACED
  • Change to Removed() and move to uncreatableComponents in ComponentChange
Cleanup
  • Delete the class
  • Update the associated CMakeLists

Datafields

This section relies a lot on the DeprecatedData and RemovedData mechanism, introduced in #3934.

Renaming a Datafield

Steps Dev-oriented changes Users-oriented changes
Do the renaming
Deprecation
(6 months)
  • Use RenamedData with the old datafield name in the component class
  • Update all scenes using the data
Renaming
(6 months)
  • Replace the RenamedData with the DeprecatedAndRemoved
Cleanup
  • Remove the DeprecatedAndRemoved member in the component class

Removing a Datafield

Steps Dev-oriented changes Users-oriented changes
Deprecation
(6 months)
  • Use a fake DeprecatedData in the component class
  • Remove all references to this Data in whole codebase
  • Update all scenes using the data
Deletion
(6 months)
  • Replace the DeprecatedData with RemovedData in the component class
Cleanup
(6 months)
  • Remove the RemovedData member in the component class

Changing Data default value

As suggested in #3563, when the default value of a Data is changed the following warning should be added in the init() function:

msg_warning_when(!d_dataName.isSet()) << "The default value of the Data " << d_dataName.getName() << " changed in v23.06 from 0.3 to 0.45.";