Jump to: navigation, search

Difference between revisions of "EMF Compare/Specifications/Template"

(First version of the specification for the improvements of the Java services modules generation)
m (nothing to see...)
Line 1: Line 1:
=Improved Java Services Modules Generation=
+
= Evolution Specification: Allow the edition textual attribute  =
 +
 
 
Current status is '''DRAFT'''
 
Current status is '''DRAFT'''
 +
 +
== Preamble  ==
 +
 +
Often, when comparing textual attribute, neither the local nor the remote value is the one the user wants to
 +
keep. We will relax the read-only constraint on textual compare viewer. As soon as the left or the right side is
 +
edited, the associated difference will be marked as rejected.
 +
 +
<br> The possible status are (roughly inspired by [http://python.org/dev/peps/pep-0001/ PEP-0001]):
 +
 +
*'''DRAFT''': Initial version and revisions based on internal feedback and discussions. DRAFT versions should never be made available outside of Obeo. They have version numbers 0.x.
 +
 +
*'''PROPOSAL''': When the document is considered ready for discussion with the client, it becomes a PROPOSAL. The first such version is numbered 1.0. Feedback from the client are integrated in further versions 1.x which are still PROPOSALs. Changes from one version to the next should be documented inside the document (as the client does not have access to the source repository).
 +
 +
*'''ACCEPTED''': Once agreement has been reached with the client, the document becomes ACCEPTED.This version becomes the authoritative one for guiding the evolution's actual implementation. It should normally be considered freezed. Any change to it should be exceptional and subject to approval by the project manager. Such changes must be clearly documented and justified.
 +
 +
*'''ARCHIVED''': Once the evolution has been implemented _and_ its specification has been integrated into the reference documentation, this document is ARCHIVED. Any further change to the same features should be another __Viewpoint Evolution__ .
 +
 +
_Relevant tickets_ (links to the Bugzilla tickets which are related to the change):
 +
 +
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=205420 Bug 205420]&nbsp;- EMF compare should handle contributions change
  
 
== Introduction  ==
 
== Introduction  ==
  
There are several issues with the current implementation used to generate an Acceleo module used to call Java services. Firstly, this generation is realized by deploying the project containing the Java services which can create several side effect if the project and its dependencies are not in a valid state. The Java Development Tools (JDT) should be used instead. Secondly, the process used to generate such module is too heavy, a contextual action should be available on a Java class to generate the matching Acceleo module. Thirdly, the Acceleo builder should be able to automate the generation of the Acceleo module used to call Java services.
+
This section should contain a summary of the proposed evolution, including why it is needed. Ideally it should be self-contained so that non-developers can get a quick overview of the evolution without reading the detailed specification.  
  
 
== Detailed Specification  ==
 
== Detailed Specification  ==
  
===Use the JDT to generate the content of the module used to call Java services===
+
This section contains the "meat" of the document. Its structure will depend on the evolution itself, but it should contain:
Due to various possible side effects and performances issues with the current solution, involving the deployment of the project containing the Java services as an OSGi bundle, the generation of the module should use the JDT to determine the signature of the methods available in the Java class. Only public methods (static or not) will be considered, just like with the old way.
+
  
===Provide a contextual action on Java files to generate a module to call the Java services===
+
*a clear description of the objective, i.e. why the evolution is needed.
The contextual action should let anyone generate an Acceleo module invoking Java services easily. This action should only be available on Java files located in an Acceleo project. It will create the same result as the wizard used to create an Acceleo module initialized with Java services. Some information, entered by the user in the wizard, will be computed thanks to various metadata in the Javadoc of the class.
+
*a justification of the approach chosen. If other approaches were considered and rejected, document it for future reference.
 +
*limits: things that are out of the scope of the evolution.
  
*The name of the module will be the name of the class starting with a lower case letter.
+
== Backward Compatibility and Migration Paths  ==
*The URI of the metamodels that should be used will be found by using the Javadoc of the Java class. In order to declare a nsURI to use, the end user should use the tag "@nsURI".
+
  
===Improve the Acceleo builder to generate automatically the module used to call the Java services===
+
Every one of the sections below should be present. Even if there is no corresponding change (for example no API change), it should exist to mention explicitly "This evolution does not change any API."
The module used to call the Java services could be created automatically by the Acceleo builder. In order to provide this feature, the builder needs to know which classes should be taken into account for the automatic generation.
+
 
 +
=== Metamodel Changes  ===
 +
 
 +
Document any change to the Viewpoint metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also.  
  
 
=== API Changes  ===
 
=== API Changes  ===
  
Those evolution have no impact on any existing API and they will create module similars to the ones generate by the wizard.
+
List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code.  
  
 
=== User Interface Changes  ===
 
=== User Interface Changes  ===
  
A new contextual action will be available on Java classes located in an Acceleo project
+
List every user-visible change in the interface. Here "user" includes not only end-users but also developpers.
  
 
=== Documentation Changes  ===
 
=== Documentation Changes  ===
  
The documentation of the Java services will be improved to specify those two new ways to generate the module used to invoke the Java services.
+
List every documentation needing an update here, starting by the New and Noteworthy documentation.  
  
 
== Tests and Non-regression strategy  ==
 
== Tests and Non-regression strategy  ==
  
Unit tests of the code generated by switching to the JDT will be put in place. There was no tests before for the "deployment based" behavior.
+
This part of the document should describe the strategy to use to correctly test the evolution and guarantee the non-regression.  
 +
 
 +
== Implementation choices and tradeoffs  ==
 +
 
 +
Any important tradeoff or choice made during the implementation should be referenced here with pros/cons leading to the final decision.
  
[[Category:Acceleo]]
+
[[Category:EMF Compare]]

Revision as of 06:24, 17 January 2013

Evolution Specification: Allow the edition textual attribute

Current status is DRAFT

Preamble

Often, when comparing textual attribute, neither the local nor the remote value is the one the user wants to keep. We will relax the read-only constraint on textual compare viewer. As soon as the left or the right side is edited, the associated difference will be marked as rejected.


The possible status are (roughly inspired by PEP-0001):

  • DRAFT: Initial version and revisions based on internal feedback and discussions. DRAFT versions should never be made available outside of Obeo. They have version numbers 0.x.
  • PROPOSAL: When the document is considered ready for discussion with the client, it becomes a PROPOSAL. The first such version is numbered 1.0. Feedback from the client are integrated in further versions 1.x which are still PROPOSALs. Changes from one version to the next should be documented inside the document (as the client does not have access to the source repository).
  • ACCEPTED: Once agreement has been reached with the client, the document becomes ACCEPTED.This version becomes the authoritative one for guiding the evolution's actual implementation. It should normally be considered freezed. Any change to it should be exceptional and subject to approval by the project manager. Such changes must be clearly documented and justified.
  • ARCHIVED: Once the evolution has been implemented _and_ its specification has been integrated into the reference documentation, this document is ARCHIVED. Any further change to the same features should be another __Viewpoint Evolution__ .

_Relevant tickets_ (links to the Bugzilla tickets which are related to the change):

  • Bug 205420 - EMF compare should handle contributions change

Introduction

This section should contain a summary of the proposed evolution, including why it is needed. Ideally it should be self-contained so that non-developers can get a quick overview of the evolution without reading the detailed specification.

Detailed Specification

This section contains the "meat" of the document. Its structure will depend on the evolution itself, but it should contain:

  • a clear description of the objective, i.e. why the evolution is needed.
  • a justification of the approach chosen. If other approaches were considered and rejected, document it for future reference.
  • limits: things that are out of the scope of the evolution.

Backward Compatibility and Migration Paths

Every one of the sections below should be present. Even if there is no corresponding change (for example no API change), it should exist to mention explicitly "This evolution does not change any API."

Metamodel Changes

Document any change to the Viewpoint metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also.

API Changes

List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code.

User Interface Changes

List every user-visible change in the interface. Here "user" includes not only end-users but also developpers.

Documentation Changes

List every documentation needing an update here, starting by the New and Noteworthy documentation.

Tests and Non-regression strategy

This part of the document should describe the strategy to use to correctly test the evolution and guarantee the non-regression.

Implementation choices and tradeoffs

Any important tradeoff or choice made during the implementation should be referenced here with pros/cons leading to the final decision.