Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Eclipse UML Generators/Contributor Guide

< Eclipse UML Generators
Revision as of 04:17, 10 July 2014 by Fabien.toral.c-s.fr (Talk | contribs) (Replace reference to project EMF Compare to Eclipse UML Generators. Seems to be a forgotten copy/paste.)


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.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 three 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 project.
  • org.eclipse.umlgen.repository contains the update site of the 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 the 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.

Build on multi-platform: [PENDING]

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

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.

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

[PENDING] See Bug 438280

The Eclipse plugin for Checkstyle can be downloaded on sourceforge.

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.

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