Skip to main content
Jump to: navigation, search

Difference between revisions of "Eclipse UML Generators/Contributor Guide"

m (Building the code)
 
Line 85: Line 85:
 
If you would like to import the projects into your workspace and let Eclipse build it, you will also find several <code>.target</code> files in the '''org.eclipse.umlgen.target''' project to configure your target platform. We recommend you use the one you are primarily targeting to install UML Generators. If you don't know what is a Target Platform, we suggest you to read [http://wiki.eclipse.org/PDE/Target_Definitions this description] and the documentation of the [http://help.eclipse.org/juno/topic/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/target_editor.htm target definition file editor].
 
If you would like to import the projects into your workspace and let Eclipse build it, you will also find several <code>.target</code> files in the '''org.eclipse.umlgen.target''' project to configure your target platform. We recommend you use the one you are primarily targeting to install UML Generators. If you don't know what is a Target Platform, we suggest you to read [http://wiki.eclipse.org/PDE/Target_Definitions this description] and the documentation of the [http://help.eclipse.org/juno/topic/org.eclipse.pde.doc.user/guide/tools/editors/target_editor/target_editor.htm target definition file editor].
  
If you don't want to build UML Generators by yourself, you have access to the last successful build from [https://hudson.eclipse.org/umlgen/job/umlgen-master/lastSuccessfulBuild/org.eclipse.umlgen$org.eclipse.umlgen.repository/ Hudson] and the promoted  builds on [PENDING].
+
If you don't want to build UML Generators by yourself, you have access to the promoted  builds on [[Eclipse_UML_Generators/Update_Sites|this page]].
  
 
== Developing Eclipse UML Generators patches or code  ==
 
== Developing Eclipse UML Generators patches or code  ==

Latest revision as of 11:15, 1 July 2015


Eclipse UML Generators
Website
Download
Community
Mailing List
Forums
Bugzilla
Open
Create New
Contribute
Browse Source


Contributing

  • You need an Eclipse user account. You already have one if you are an Eclipse commiter or have a Bugzilla account. Otherwise, use this form.
  • Sign the Eclipse Contributing License Agreement (CLA) : Please go to your user page , then to the CLA tab once you’re logged in and follow the instructions.
  • Make sure you use the proper user information on your git clone’s configuration :
    • $ cd <path/to/repository>
    • $ git config --local user.name "<Full Name>"
    • $ git config --local user.email "<your.mailyourmail.com>"
  • Make small logical changes.
  • Provide a meaningful commit message.

Eclipse UML Generators uses gerrit for peer reviews. To configure it on your repository, please look up how to setup your SSH keys and remote on the wiki [soon]. A detailed guide on the commit message’s format can be found further down this same page.

Once properly configured, you will be able to request a review by simply pushing your commit on this new remote.

Environment

  • Java
Eclipse UML Generators is built against Java 1.5. Though it is compatible with later versions and will thus run flawlessly on 1.5, 1.6 and 1.7 virtual machines, development should make use of 1.5 APIs and avoid any reference to more recent code so as to prevent compilation errors.
  • Eclipse
Developing on Eclipse UML Generators requires the use of Eclipse 4.4 (Luna) at least, though it is possible to use the latest releases as well.
It can be obtained through the Eclipse download page. The easiest way to set up your environment is to download the Eclipse Modeling Tools bundle since it will already contain most of our dependencies, except for Guava.
All of the following can be obtained through the simultaneous release's update site. From the Eclipse you've installed, use the Help > Install New Software... menu. In the dialog that pops up, locate the update site of your release (it should be labelled Eclipse <name of release> Repository). The list that loads below will contain the necessary projects that you just have to install.
We'll go through how to obtain them separately.
  • Guava
Eclipse UML Generators depends on version 15 of google's Guava library. It can be installed from the Orbit update site.
  • UML
Eclipse UML Generators heavily relies on UML and requires version 5.0 at least.
  • Acceleo
Eclipse UML Generators heavily relies on Acceleo and requires version 3.5 at least.

Checking out the code

The code of Eclipse UML Generators is located on a git repository. You can check it out with the command :

git clone git://git.eclipse.org/gitroot/umlgen/org.eclipse.umlgen.git

The repository contains a folder per generator at its root :

  • org.eclipse.umlgen for features federating the generators
  • org.eclipse.umlgen.gen.c for C generator
  • org.eclipse.umlgen.gen.java for Java generator
  • org.eclipse.umlgen.gen.rtsj for Autojava/RTSJ generator
  • org.eclipse.umlgen.reverse.c for C reverser

and a releng folder with four sub-folders:

  • org.eclipse.umlgen.parent is a non-code plugin which serves as the location of our parent pom. It otherwise contains our code style. You will need this plugin in your workspace whatever you work on as it holds the checkstyle configuration of our plugins (see Checkstyle below).
  • org.eclipse.umlgen.build contains the common configuration to build the whole project.
  • org.eclipse.umlgen.target contains the target platforms used to build the project.
  • org.eclipse.umlgen.repository contains the update site of the whole project.


Each generator folder contains sub-folders:

  • plugins: It contains all the plugins of the generator.
  • features: It contains the features of the generator.
  • tests: It contains the tests of the generator.
  • doc: It contains the user documentation of the generator.
  • releng: Like the common releng folder, it contains the org.eclipse.umlgen.xxx.yyy.build and org.eclipse.umlgen.xxx.yyy.repository. This enables to individually build each generator.

All of our plugins' name are prefixed with org.eclipse.umlgen. If the plugin is part of an Acceleo generator, .gen will be added to the name (org.eclipse.umlgen.gen). If it is part of a reverser, .reverse will be used. Here is the expected pattern :

org.eclipse.umlgen[.gen|.reverse][.<technology.to.produce.or.consume>][.<specific.part>]

Building the code

Eclipse UML Generators can be built using maven. Go to the releng/org.eclipse.umlgen.build or zzz/releng/org.eclipse.umlgen.xxx.yyy.build folder and just do a

 mvn clean package

With zzz, the generator folder to build alone.

If you would like to import the projects into your workspace and let Eclipse build it, you will also find several .target files in the org.eclipse.umlgen.target project to configure your target platform. We recommend you use the one you are primarily targeting to install UML Generators. If you don't know what is a Target Platform, we suggest you to read this description and the documentation of the target definition file editor.

If you don't want to build UML Generators by yourself, you have access to the promoted builds on this page.

Developing Eclipse UML Generators patches or code

Developing a new feature

When a new feature is to be developed, it should be announced to the community with the following messages:

  • Open a feature enhancement bug on the bugzilla describing the new feature.
  • Create a specification page on the wiki following the provided template. A link to the bugzilla should be added to this page and a reference to this page should be added in a comment of the bugzilla. The name of the wikipage should be Eclipse_UML_Generators/Specification/<ComponentID>/<DescribingTitle>. The page should be added to the category Category:Eclipse_UML_Generators/Specification (Add [[Category:Eclipse_UML_Generators/Specification]] text at the bottom of the page).
  • Announce that the development has started for this feature on the developers mailling list and provide a link to the previously created bugzilla and the specification wiki page.

When the feature is completed, the community should be told:

  • Add a comment to the bugzilla with a reference to the commit(s) and/or gerrit review(s) in which the feature has been implemented, completed.
  • Close the bug.
  • Mark the specification as ACCEPTED until the documentation has been updated and mark it as ARCHIVED once done.

Specifications

Every new feature or major change should be documented in a short specification, the template is available here

Target Platform

UML Generators is compatible with Eclipse Luna (4.4). Target platform for Luna is provided within the org.eclipse.umlgen.target plugin.

The target platform can be set through the preference page accessible via Window => Preferences => Plug-in Development => Target Platform. More information on how to set a target platform for development can be found in the Eclipse help.

Please also double check that you use JDK 5 to 7 APIs. UML Generators is built against Java 7 and will show compilation errors if using later APIs.

Contributing the patch

When you are ready to contribute the patch, you can push it for review. The Eclipse UML Generators Team uses Gerrit to simplify the review and feedback process, please follow the instructions on The dedicated Page.

Planning

[PENDING]

Code Style

Copyright

Every new file should contain a copyright as its very first lines. Copyrights should match the following form, adapted according to the contributor's company (or his own name if he is the copyright holder himself).

/*******************************************************************************
 * Copyright (c) 2012 Obeo.
 * 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:
 *     Obeo - initial API and implementation
 *******************************************************************************/

When modifying a file which existing copyright does not match the contributor's, the copyright should be modified to reflect it.

/*******************************************************************************
 * Copyright (c) 2012 Obeo and others.
 * 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:
 *     Obeo - initial API and implementation
 *     Luca Lashnikov - bug xxxxxx (or very simple description of the change if no related bug)
 *******************************************************************************/

When modifying an older file which copyright's year range does not match the current, its first line should be updated to contain the year of the change :

Copyright (c) 2012, 2013 Obeo.

Checkstyle

The UML Generators team uses Checkstyle with its own set of rules in order to have an homogeneous code style throughout the plugins and features.

The Eclipse plugin for Checkstyle can be downloaded on sourceforge. EMF Compare makes use of Checkstyle 6.*. Once installed, it will be automatically applied to all existing UML Generators plugins as they are already configured to use it.

You need to have the org.eclipse.umlgen.parent plugin in your workspace.

New projects should use the same set of rules :

  1. Right-click on the project on which to configure Checkstyle and select "Properties",
  2. In the "Checkstyle" category, go to the "Local Checkstyle configuration" tab,
  3. Hit "New" and select "project-relative configuration" from the "type" drop down menu. Set the name of this configuration as you see fit ("Eclipse UML Generators" for example) and click the "Open..." button for the localization.
  4. Browse to "org.eclipse.umlgen.parent/codeStyle" and select UMLGenCheckstyleConfiguration5.xml. Hit "Ok" twice to end this wizard.
  5. Go back to the "General" tab, then tick "Activate Checkstyle on this project"
  6. In the drop-down below, select the configuration you just created, then click OK to close the properties dialog.
  7. That's it. Your project will now go through the UML Generators Chekstyle rules on each compilation.

Note that Checkstyle errors are not considered fatal compilation errors : you can still run code with checkstyle errors. Nearly each of UML Generators check is set to report an error though, as we always try and comply to these rules.

Code Formatting

Note that all Eclipse UML Generators plugins are already configured to make use of this formatter.

  1. Click on Window > Preferences,
  2. Browse to the Java > Code Style > Formatter category and click on the "Import" button,
  3. Browse to the "<workspace path>/org.eclipse.umlgen.parent/CodeStyle" directory and select "UMLGenFormatter.xml",
  4. Hit Ok twice to close the preferences dialog.

Your formatter will now comply to Eclipse UML Generators code style. Hitting ctrl+shift+F in a java editor will format your class to follow this style.

API Tooling

[PENDING]

MUST DO to create/contribute a new Eclipse UML generator

  • Content
    • It has to be contributed with a test project, a representative data set and a detailed test procedure/strategy at least. The tests have to run successfully. Non-regression tests consist in comparing with reference relative generated code or model. The use of JUnit would be much better to automatize these tests.
    • A user and functional documentation has to exist with the contribution at least. It may be embedded in a "doc" plug-in (like org.eclipse.umlgen.gen.java.doc). The add of a technical specification on this wiki would be much better, as specified in the process.
  • Frameworks and API
    • A new UML to Text generator has to rely on Acceleo.
    • It has to rely on the specified environment. If Guava is used, its version has to be compliant with 15.0.0, the Import-Package has to be constrained to the effectively used version in the plug-in and no class from Guava has to be exposed in the potential APIs.
  • Conventions
    • It has to conform with the specified naming convention, code style and code template, with automatic format.
    • Code has to conform with the standard development conventions.
    • The plug-ins have to be configured in order to use UTF-8 text file encoding and a UNIX text file line delimiter.
    • The plug-in provider name has to be "Eclipse UML Generators"

Interesting links

Back to the top