Bug 417455

Description Christian Damus 2013-09-17 16:10:43 EDT

(raised from bug 415373 comment #1)

Kepler Release and SR1 RC builds.

The org.eclipse.papyrus.uml.documentation plug-in provides a UML-specific documentation manager that attaches documentation to model elements via owned comments with the «documentation» stereotype applied.  The problem is that this plug-in registers its documentation manager only against old UML namespaces, up to version 3.0.0, not the 4.0.0 namespace that shipped with the Kepler release.

Consequently, the default annotation-based scheme for attaching documentation and resources is used by the Kepler release of Papyrus and, so far, Luna.

Fixing this by registering UMLDocumentationManager on the latest UML namespace in the Luna release (or a Kepler SR) would cause immediate data loss upon software update, as existing models would start ignoring all of the data in the annotations.  AFAICS, there is no provision for migrating data from one documentation manager to another, so all existing data would simply be ignored.

However, I'm not sure whether this is worse than the data loss already suffered by any users that upgraded to the Kepler release, because that migrated their UML models from the 3.0.0 namespace to 4.0.0.  This then caused Papyrus Kepler to ignore all of the documentation information stored in the «documentation» comments because it is looking for the annotations.  Fixing the manager registration would actually *restore* that information.

So, which is the better course of action to address the problem?

  * continue without the UML-specific documentation manager for Luna and
    subsequent releases (the oep.uml.documentation* plug-ins then should
    be removed from the build)
     
  * add the registration of the UMLDocumentationManager for the 4.0.0
    namespace and hope that the recovery of documentation data lost in
    Kepler outweighs the loss of documentation data in Luna

  * add the registration of the UMLDocumentationManager for the 4.0.0
    namespace and implement automatic migration of existing model
    documentation found in the annotation format to the profile format