Difference between revisions of "MoDisco/DeveloperGuide"

From Eclipsepedia

Jump to: navigation, search
(Adding of metamodel naming rules)
(Infrastructure plug-ins naming)
 
(4 intermediate revisions by 2 users not shown)
Line 32: Line 32:
 
For common components:  
 
For common components:  
  
*a plug-in org.eclipse.gmt.modisco.infra.common.core  
+
*a plug-in org.eclipse.modisco.infra.common.core  
 
**contains non-graphical components  
 
**contains non-graphical components  
*a plug-in org.eclipse.gmt.modisco.infra.common.ui (if necessary)  
+
*a plug-in org.eclipse.modisco.infra.common.ui (if necessary)  
 
**if necessary, contains graphical components (except editor features)
 
**if necessary, contains graphical components (except editor features)
  
 
For each infrastructure component named x (except OMG standards implementation):  
 
For each infrastructure component named x (except OMG standards implementation):  
  
*a plug-in org.eclipse.gmt.modisco.infra.x  
+
*a plug-in org.eclipse.modisco.infra.x  
 
**contains the meta-model implementation of the component x (if necessary)  
 
**contains the meta-model implementation of the component x (if necessary)  
*a plug-in org.eclipse.gmt.modisco.infra.x.core  
+
*a plug-in org.eclipse.modisco.infra.x.core  
 
**contains non-graphical components  
 
**contains non-graphical components  
*a plug-in org.eclipse.gmt.modisco.infra.x.editor  
+
*a plug-in org.eclipse.modisco.infra.x.editor  
 
**if necessary, contains the component allowing to execute the Eclipse’s edit action.  
 
**if necessary, contains the component allowing to execute the Eclipse’s edit action.  
*a plug-in org.eclipse.gmt.modisco.infra.x.ui (if necessary)  
+
*a plug-in org.eclipse.modisco.infra.x.ui (if necessary)  
 
**if necessary, contains the graphical components.
 
**if necessary, contains the graphical components.
  
 
For each subcomponent y of the infrastructure’s component x  
 
For each subcomponent y of the infrastructure’s component x  
  
*a plug-in org.eclipse.gmt.modisco.infra.x.y  
+
*a plug-in org.eclipse.modisco.infra.x.y  
*a plug-in org.eclipse.gmt.modisco.infra.x.y.core  
+
*a plug-in org.eclipse.modisco.infra.x.y.core  
*a plug-in org.eclipse.gmt.modisco.infra.x.y.editor  
+
*a plug-in org.eclipse.modisco.infra.x.y.editor  
*a plug-in org.eclipse.gmt.modisco.infra.x.y.ui (if necessary)
+
*a plug-in org.eclipse.modisco.infra.x.y.ui (if necessary)
  
 
=== Technology plug-ins naming ===
 
=== Technology plug-ins naming ===
Line 59: Line 59:
 
For each component dedicated to the technology x :  
 
For each component dedicated to the technology x :  
  
*a plug-in org.eclipse.gmt.modisco.x : contains the meta-model implementation  
+
*a plug-in org.eclipse.modisco.x : contains the meta-model implementation  
*a plug-in org.eclipse.gmt.modisco.x.discoverer : contains the basic discoverers  
+
*a plug-in org.eclipse.modisco.x.discoverer : contains the basic discoverers  
*a plug-in org.eclipse.gmt.modisco.x.discoverer.y : for each additional discoverer  
+
*a plug-in org.eclipse.modisco.x.discoverer.y : for each additional discoverer  
*a plug-in org.eclipse.gmt.modisco.x.edit : EMF edit classes  
+
*a plug-in org.eclipse.modisco.x.edit : EMF edit classes  
*a plug-in org.eclipse.gmt.modisco.x.editor : EMF editor classes and reflexive editor customization  
+
*a plug-in org.eclipse.modisco.x.editor : EMF editor classes and reflexive editor customization  
*a plug-in org.eclipse.gmt.modisco.x.custom : UICustom + facet + queries  
+
*a plug-in org.eclipse.modisco.x.custom : UICustom + facet + queries  
*a plug-in org.eclipse.gmt.modisco.x.zconverter : converter from x to z
+
*a plug-in org.eclipse.modisco.x.zconverter : converter from x to z
  
 
=== Use-cases plug-ins naming ===
 
=== Use-cases plug-ins naming ===
Line 71: Line 71:
 
For each component dedicated to a use-case x:  
 
For each component dedicated to a use-case x:  
  
*a plug-in org.eclipse.gmt.modisco.usecase.x
+
*a plug-in org.eclipse.modisco.usecase.x
  
 
=== For each component ===
 
=== For each component ===
Line 102: Line 102:
 
The Eclipse API Tools must be activated on each MoDisco project, with an API baseline set to a folder containing the MoDisco plug-ins from the previous release. This is to ensure that no unintentional API breakage happens from release to release.  
 
The Eclipse API Tools must be activated on each MoDisco project, with an API baseline set to a folder containing the MoDisco plug-ins from the previous release. This is to ensure that no unintentional API breakage happens from release to release.  
  
The following article explains how to use the API Tools:<br> [https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/ https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/]
+
The following article explains how to use the API Tools:<br> [https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/ https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/
  
 
= Java Compliance Level =
 
= Java Compliance Level =
Line 141: Line 141:
 
MoDisco help content for Eclipse IDE is generated with the [[Mylyn|Mylyn]] Project directly from the MoDisco Wiki.
 
MoDisco help content for Eclipse IDE is generated with the [[Mylyn|Mylyn]] Project directly from the MoDisco Wiki.
  
Main documentation project org.eclipse.gmt.modisco.doc references one project per main feature.
+
Main documentation project org.eclipse.modisco.doc references one project per main feature.
Each of these project contains a script to generate the toc.xml  (see org.eclipse.gmt.modisco.infra.doc as an example)
+
Each of these project contains a script to generate the toc.xml  (see org.eclipse.modisco.infra.doc as an example)
  
 
To include a wiki page in the help content, it is necessary to add its mediawiki internal link to those script, as shown in the following:
 
To include a wiki page in the help content, it is necessary to add its mediawiki internal link to those script, as shown in the following:
Line 186: Line 186:
 
When editing the tabs for a page, be careful to copy your changes to each page that uses the same tabs.
 
When editing the tabs for a page, be careful to copy your changes to each page that uses the same tabs.
 
[[Category:MoDisco]]
 
[[Category:MoDisco]]
 +
 +
 +
= IP Tracking =
 +
 +
Each time a developer contributes to a file, he has to had his name and a reference to corresponding bug in the contributors section of the file header.
 +
 +
Example:
 +
 +
/**********************************************************************************
 +
  * Copyright (c) 2011 Mia-Software.
 +
  * All rights reserved. This program and the accompanying materials
 +
  * are made available under the terms of the Eclipse Public License v1.0
 +
  * which accompanies this distribution, and is available at
 +
  * http://www.eclipse.org/legal/epl-v10.html
 +
  *
 +
  * Contributors:
 +
  *    Nicolas Guyomar (Mia-Software) - Bug 333652 Extension point offering the possibility to declare an EPackage browser
 +
  *    Fabien Giquel (Mia-Software) -Bug 335218 - Extension point for registering EObject, EPackage, model editor
 +
  *    Nicolas Bros (Mia-Software) - Bug 335218 - Extension point for registering EObject, EPackage, model editor
 +
  ***********************************************************************************/

Latest revision as of 09:30, 16 August 2011


Contents

[edit] Naming

[edit] Metamodel naming

http://www.eclipse.org/MoDisco/<metamodel>/0.1.1/<package_path>-<experimentation>-<implementation>

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java

http://www.eclipse.org/MoDisco/Java/0.1.1/java

We need to be able to add a suffix to identify the implementation variants (CDO, MinimalEObject, etc.).

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java-CDO

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java-MinimalEObject

We also need to be able to identify meta-model variants. For example, in the MoDisco's Java tool we have a metamodel which does not contain opposite links.

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java-noopposite

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java-noopposite-CDO

http://www.eclipse.org/MoDisco/Java/0.1.incubation/java-noopposite-MinimalEObject

[edit] Plug-ins naming

[edit] Infrastructure plug-ins naming

For common components:

  • a plug-in org.eclipse.modisco.infra.common.core
    • contains non-graphical components
  • a plug-in org.eclipse.modisco.infra.common.ui (if necessary)
    • if necessary, contains graphical components (except editor features)

For each infrastructure component named x (except OMG standards implementation):

  • a plug-in org.eclipse.modisco.infra.x
    • contains the meta-model implementation of the component x (if necessary)
  • a plug-in org.eclipse.modisco.infra.x.core
    • contains non-graphical components
  • a plug-in org.eclipse.modisco.infra.x.editor
    • if necessary, contains the component allowing to execute the Eclipse’s edit action.
  • a plug-in org.eclipse.modisco.infra.x.ui (if necessary)
    • if necessary, contains the graphical components.

For each subcomponent y of the infrastructure’s component x

  • a plug-in org.eclipse.modisco.infra.x.y
  • a plug-in org.eclipse.modisco.infra.x.y.core
  • a plug-in org.eclipse.modisco.infra.x.y.editor
  • a plug-in org.eclipse.modisco.infra.x.y.ui (if necessary)

[edit] Technology plug-ins naming

For each component dedicated to the technology x :

  • a plug-in org.eclipse.modisco.x : contains the meta-model implementation
  • a plug-in org.eclipse.modisco.x.discoverer : contains the basic discoverers
  • a plug-in org.eclipse.modisco.x.discoverer.y : for each additional discoverer
  • a plug-in org.eclipse.modisco.x.edit : EMF edit classes
  • a plug-in org.eclipse.modisco.x.editor : EMF editor classes and reflexive editor customization
  • a plug-in org.eclipse.modisco.x.custom : UICustom + facet + queries
  • a plug-in org.eclipse.modisco.x.zconverter : converter from x to z

[edit] Use-cases plug-ins naming

For each component dedicated to a use-case x:

  • a plug-in org.eclipse.modisco.usecase.x

[edit] For each component

For each component or sub-component x :

  • a plug-in x.doc referred by the parent component
  • a plug-in x.tests
  • a plug-in x.examples.y
    • "y" is the example name if it exists more than one example for the component "x".

[edit] Feature naming

  • The feature name suffixed by ".feature"
  • Feature id: not suffixed by ".feature" (can have the same name as a plug-in)

[edit] Package naming

  • Prefixed by the name of the plug-in containing the package
  • The EMF generation parameters must be changed to conform to this rule

[edit] Coding conventions

Coding conventions

[edit] APIs visibility

see MoDisco API Visibility

The Eclipse API Tools must be activated on each MoDisco project, with an API baseline set to a folder containing the MoDisco plug-ins from the previous release. This is to ensure that no unintentional API breakage happens from release to release.

The following article explains how to use the API Tools:
[https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/ https://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/

[edit] Java Compliance Level

Java 5 compliance level is required. Take care of:

  • checking compilation, at least once, with Java 5 compiler compliance level and using a JRE5 library
  • indicating on plugin Manifest "Bundle-RequiredExecutionEnvironment: J2SE-1.5"

[edit] SuppressWarnings("rawtypes")

Eclipse 3.6 M3 introduced a change in the way it handles "@SuppressWarnings" for generic types that are used without specifying the type parameter.

Previously, @SuppressWarnings("unchecked") was used to suppress the corresponding warning. Now, Eclipse expects @SuppressWarnings("rawtypes") instead (see bug 290034).

Problem is, this doesn't seem to be supported in other Java compilers (like the Sun or IBM Java compilers). It will eventually be, but not until Java 7, from what I could gather.

The MoDisco build uses an IBM compiler which is installed on the build machine, and which emits warnings whenever it encounters this @SuppressWarnings("rawtypes") it doesn't understand.

A solution to keep both Eclipse and the build happy is to tell Eclipse to keep its old behavior, by adding the following line in the VM arguments in eclipse.ini:

-DsuppressRawWhenUnchecked=true

And continue using @SuppressWarnings("unchecked").

[edit] Versioning

All plug-ins must have the same version as the project version (current = 0.7.1, next = 0.8.0)

[edit] Testing

To install SWTBot the following update site must be used: http://download.eclipse.org/technology/swtbot/helios/dev-build/update-site

[edit] MoDisco Wiki

[edit] Help Content

MoDisco help content for Eclipse IDE is generated with the Mylyn Project directly from the MoDisco Wiki.

Main documentation project org.eclipse.modisco.doc references one project per main feature. Each of these project contains a script to generate the toc.xml (see org.eclipse.modisco.infra.doc as an example)

To include a wiki page in the help content, it is necessary to add its mediawiki internal link to those script, as shown in the following:


<path name="MoDisco/Components/KDM" title="KDM" />

<path name="MoDisco/Components/KDM/Documentation/0.9" title="KDM Version 0.9" tocParentName="MoDisco/Components/KDM"/>

<path name="MoDisco/Components/KDM/New_And_Noteworthy" title="KDM New And Noteworthy" tocParentName="MoDisco/Components/KDM"/>

[edit] Template

MediaWiki templates are used to organize MoDisco components in several tabs.

{{ MoDiscoTabs | <nameOfSection> |

{{ MoDiscoTab | <nameOfSection> | <nameOfTheTab> | <version number> }}

}}

Eg :

{{MoDiscoTabs|KDM| {{MoDiscoTab|KDM|Documentation|0.7}}{{MoDiscoTab|KDM|Architecture|0.8}} }}

will display :

MoDisco
Website
Download
Community
Mailing ListForums
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse SourceProject Set File

The code has to be copy-pasted on top of each wiki page.

When editing the tabs for a page, be careful to copy your changes to each page that uses the same tabs.


[edit] IP Tracking

Each time a developer contributes to a file, he has to had his name and a reference to corresponding bug in the contributors section of the file header.

Example:

/**********************************************************************************
 * Copyright (c) 2011 Mia-Software.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Nicolas Guyomar (Mia-Software) - Bug 333652 Extension point offering the possibility to declare an EPackage browser
 *    Fabien Giquel (Mia-Software) -Bug 335218 - Extension point for registering EObject, EPackage, model editor
 *    Nicolas Bros (Mia-Software) - Bug 335218 - Extension point for registering EObject, EPackage, model editor
 ***********************************************************************************/