Skip to content

Latest commit

 

History

History
237 lines (207 loc) · 5.75 KB

45_Lifecycle_mechanisms.md

File metadata and controls

237 lines (207 loc) · 5.75 KB
Raw

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_DEPRECATED_HEADER
  • Add as CreatableMoved() in deprecatedComponents in ComponentChange
Deletion
(6 months)
  • In the old compatibility header, change the macro for SOFA_DISABLED_HEADER
  • 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 empty header with old name including the new file
  • Add a C++ alias for the component name
  • Add a macro SOFA_ATTRIBUTE_DEPRECATED on this alias
  • 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
Renaming
(6 months)
  • Change the C++ alias to be on DeprecatedOrRemoved in the component class
  • 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 C++ alias in the component class

Removing a Component

Steps Dev-oriented changes Users-oriented changes
Deprecation
(6 months)
  • use a macro to deprecate the class SOFA_DEPRECATED_HEADER_NOT_REPLACED
  • Add as Deprecated() in deprecatedComponents in ComponentChange
Deletion
(6 months)
  • Empty the class and use the macro SOFA_DISABLED_HEADER_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 a fake DeprecatedData with the old datafield name in the component class
  • Update all scenes using the data
Renaming
(6 months)
  • Replace the DeprecatedData with RemovedData in the component class
Cleanup
  • Remove the RemovedData 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.";