Capella/Technical Information

From Wiki
Jump to: navigation, search

Technical Information

Introduction

This page describes the development process for Capella. In particular, it describes the methodology to be followed to contribute to Capella and the tooling provided to achieve this goal.

A good starting point for reading is PolarSys The_Forge that gives an overview of the process in terms of tooling.

Applicable Document

The instructions in this page follow the rules defined in the PolarSys Software Development Process for Capella and Kitalpha document. Please refer to this document for additional information.

Development Process

Requirements

Any change, whether as bug correction or evolution made to Capella, requires the creation and acceptance of a bug in Bugzilla.
Requirements, in case of an evolution, are to be proposed in the description of the bug in Bugzilla. Evolutions are also open to debate in the forum for instance. They also will be discussed in roadmap meetings but any proposal is welcome.
List of requirements in the true sense of the word will be made available later. Current functionalities are described in the documentation.

Change Management

Bugzilla is the general-purpose bug tracker used for Capella. It can be accessed using http://polarsys.org/bugs/describecomponents.cgi?product=Capella

Development

Development Environment Configuration (Automated Setup)

The easiest way to setup a capella development environment is by using the eclipse installer. See the Oomph Setup page for more info.

Development Environment Configuration (Manual)

If you cannot use the eclipse installer for some reason, a development environment can also be configured manually:

  • First, download and run Capella Studio ;
  • After launch, open Help then Install new software... wizard ;

(e.g. For Capella 1.0.0 based on Eclipse Juno: http://download.eclipse.org/egit/updates-3.3.2)

  • Tick Eclipse Git Team Provider then Next twice and Finish.
  • Wait and Accept when asked for restart ;
  • Open Windows then Open Perspective and select Other.. Git ;

Clone repository from Gerrit

  • Select Clone a Git repository for cloning one of Capella Gerrit repository (Capella, Capella-addons, Capella-studio) or Add an existing local Git repository in case a Git repository has been cloned manually (by command-line for instance) ; For the following part, we will focus on the first option (i.e. Cloning a repository) ;
  • You can find different URIs for Capella repositories below ;
  • Type in the wizard field URI the selected Capella Gerrit repository URI of interest ; All other fields are filled ;
  • Note: For URIs, <contributor_id> and <http_password> can be found at this URL ; You need to have a PolarSys account (in case you do not have one, use this link to create one) and be logged in at this link to be able to see this webpage ; You must generate your http password once with the given button ; This procedure is described here ;
  • Then you can fill the wizard for cloning the Capella Gerrit repository of interest ;
  • The repository is now displayed in the Git Repositories view on the left-hand corner ; Let us configure Gerrit for reviews ;

Gerrit configuration for the Git repository

  • Expand the repository, and open the contextual menu on Remotes then origin. A wizard is displayed ;
  • Push URI shall be filled ; Otherwise, use the same as previously entered ;
  • Enter Destination branch of interest ; Always use master ;
  • A decorator is added to the repository in Git Repositories view showing Gerrit configuration succeeded ;
  • A few remaining steps before you can start making changed ;
  • Expand the repository in Git Repositories view ; Expand Branches then Remote Tracking folder ;
  • Double-click on origin/master branch in order to create a local working branch ;
  • Select Checkout as New Local Branch when prompted ;
  • The branch is displayed in Branches / Local folder ;
  • Now right-click on Working Directory folder and select Import Projects... ;
  • Projects are imported into the workspace ; You can go back to Capella Studio perspective ;

Creating and updating a Gerrit change request

  • Make sure you created a Bugzilla ticket before starting work!
  • Perform some changes in the projects ; Open Window then Show View and Git Staging ;
  • Drag-and-drop modified files from the Unstaged Changes field to the Staged Changes ;
  • Fill the Author i.e. contributor_id in Gerrit page and associated e-mail address ; Same for Committer Field ;
  • Enter the commit message respecting the chart written for commit message formatting here ;
  • Click on Add Signed-off-by button ; Click on Commit button ;
  • Go back to Git perspective ;
  • Right-click on the repository and select Push to Gerrit option ;
  • Verify the Gerrit branch is master prior to finish ;
  • The Eclipse Git tooling shows a dialog after its push, which contains, if the push was successful a URL to the Gerrit review. Is also contains error messages in case the push was not successful ;
  • Wait for the review!

Improve a change based on review feedback

If the review process has resulted review comments explaining how to improve the proposed patch, you will have to adjust the patch. To do so, you amend the commit in your local repository and push the improved commit to Gerrit.

As you amend the commit, the same Change-Id is used and the Gerrit review system identifies the change as update of the existing change. The Git Staging view allows amending the last commit by clicking the amend button.

Further details at this address.

License headers for new source files

Before submitting a patch, make sure that newly added source files have a proper license header. The license header must be applied to .java files, plugin.xml, plugin.properties files. The eclipse releng tools makes it easy to apply a license header to existing source files. Documentation is here

URIs for Capella repositories

Obviously the first thing we need to do is get the source that we are going to be modifying.

Capella Git

For consultation only, Capella git repository can be cloned directly using either:

git://git.polarsys.org/gitroot/capella/capella.git

or

ssh://git.polarsys.org/gitroot/capella/capella.git

Capella Gerrit

For modifications, Capella Gerrit repository must be used. It can be cloned using:

git clone https://<contributor_id>:<http_password>@git.polarsys.org/r/capella/capella

Capella Addons

A specific repository has been created for managing Capella addons.

The same work procedure applies for this repository.

For consultation only:
----------------------
  git://git.polarsys.org/gitroot/capella/capella-addons.git

or

  ssh://git.polarsys.org/gitroot/capella/capella-addons.git


For making modifications:
-------------------------
  git clone https://<contributor_id>:<http_password>@git.polarsys.org/r/capella/capella-addons

Capella Studio

A specific repository has been created for managing Capella Studio.

The same work procedure applies for this repository.

For consultation only:
----------------------
  git://git.polarsys.org/gitroot/capella/capella-studio.git

or

  ssh://git.polarsys.org/gitroot/capella/capella-studio.git


For making modifications:
-------------------------
  git clone https://<contributor_id>:<http_password>@git.polarsys.org/r/capella/capella-studio.git

Capella Source Breakdown

Each directory is composed by two sub-directories, features and plugins.
Capella source code is organized as follow:

  • Common: Generic plugins, independent from Capella metamodel. Used by various plugins ;
  • Core: Plugins dependent from Capella metamodel (Regarding charts, transitions, model validation, queries on semantic browser, property views, etc.) ;
  • Legacy : Obsolete dependencies ;
  • Doc: Capella documentation plugins - documentation as Eclipse documentation (e.g. Eclipse help menu) ;
  • M2: Capella metamodel (ecore files) ;
  • Releng : Code generation plugins (Generate Capella EMF code from ecore metamodels) and generation of builds and continuous integration jobs using EGF. Not intended to be imported into Eclipse. Designed to be used within a PolarSys Kitalpha environment.

Capella Metamodel

Getting the Metamodel

There are two ways to retrieve Capella Metamodel ecore files :

  • From the builds available on Hudson, open the plugins (with winzip, 7zip, ...) then extract the ecore files from the sub-directories model:
    • org.polarsys.capella.common.data.core.gen
    • org.polarsys.capella.common.data.behavior.gen
    • org.polarsys.capella.common.data.activity.gen
    • org.polarsys.capella.core.data.gen
  • From Capella git repository in the directories:
    • GITROOT/org.polarsys.capella/m2/plugins/org.polarsys.capella.common.data.def/model
    • GITROOT/org.polarsys.capella/m2/plugins/org.polarsys.capella.core.data.def/model

Generating the Metamodel

  • Import all releng project, *gen, *.gen.edit from core and common plugins, and m2 folder ;
  • Do your modifications into m2 folder ecore (data.def) ;
  • Run EGF Activity org.polarsys.capella.common.extension.migration.egf / G3&G4, this will copy data.def M2 into data.gen ;
  • Run org.polarsys.capella.core.egf root EGF Activity to generate EMF code.

Release Engineering

Hudson Continuous Integration System

Capella HIPP (Hudson instance) is available at:

https://hudson.polarsys.org/capella/

Download Space / Storage

The storage place for Capella milestones, snapshots and documentation is available at:

http://download.polarsys.org/capella/

Third-party Dependencies

Capella add-ons depend on Capella plugins in order to be built.

Capella solution depends on:

  • QueryLegacy
  • Eclipse Orbit
  • EMF Diff/Merge
  • Patterns
  • Sirius
  • Kitalpha
  • Eclipse plugins

These dependencies are resolved during the build, the path to their update site is provided in the build model.

Please continue to the next section.

Hudson Jobs Configuration

Jobs are separated between Capella solution and its add-ons but the underlying building process is the same.

In the source code, identify the releng plugin:

  • org.polarsys.capella.core.releng for Capella
  • org.polarsys.capella-addons.releng for add-ons;

They are based on EGF factory tool and use provided portfolios for Modeling and Generating a build chain for Hudson continuous integration system.

The release engineering plugins (releng) are composed of:

  • egf directory that contains the Factory Component:
    • Description of the input Jobs models
    • Definition of contrats (example: generation output directory)
  • model directory that contains the build models for Hudson Jobs
    • Description of the steps to produce the builds


EGF Build


For Capella and add-ons, we specified the generation output path as:

platform:/resource/org.polarsys.capella.core.releng.jobs/jobs
platform:/resource/org.polarsys.capella-addons.releng.jobs/jobs

In this sense, running the EGF Activity from the Factory Component root element will generate - and override - into the latter.


EGF Result


The build chain generated - in our case build.xml - is used for creating/updating Hudson Jobs.

Example for an add-on Job configuration:


Hudson Job Configuration


Note: The "Branche to build" field is very important!


Hudson Job Configuration


Hudson promotion

You can configure artifacts promotion with the following script

Hudson-promotion-configuration.png


#!/bin/bash

echo ""
echo ""
echo "+---------------------------------------------------------------------+"
echo "|                                                                     |"
echo "|           Promotion Script 20151221 by TGS MDE Team                 |"
echo "|                                                                     |"
echo "|           Applied on $PROMOTED_JOB_NAME with version ${version}     |"
echo "|                                                                     |"
echo "|           Copyright: Polarsys.org                                   |"
echo "|           Visit us: http://polarsys.org/capella                     |"
echo "|                                                                     |"
echo "+---------------------------------------------------------------------+"
echo ""
echo ""


DELIVER_DIR="/home/data/httpd/download.polarsys.org/capella/core/platform/releases/${version}/juno"

if [ -d "$DELIVER_DIR" ]; then
  rm -rf "$DELIVER_DIR"
fi

mkdir -p "$DELIVER_DIR"

echo ""
echo "###################### ARTIFACTS TO BE PROMOTED  ######################"

cd $HUDSON_HOME/jobs/$PROMOTED_JOB_NAME/builds/$PROMOTED_NUMBER/archive/result/publish
ls

echo ""
echo "###################### PROMOTING...              ######################"

cp *.tar.gz *.zip "$DELIVER_DIR"

Testing

  • Test suite is currently being refactored.
  • Tests description is planned for the year.

Documentation

Capella

Since Capella 1.0.0, documentation is embedded into the workbench. It is available through Help menu and Capella guide section in the window that opens.

Capella documentation is stored in Capella Git repository git.polarsys.org/c/capella/capella.git/tree/doc/plugins.

To create/update documentation, Mylyn/Wikitext must be installed in you IDE.

Some characteristics of a documentation plugin for Capella:

  • Contribute to the extension point org.eclipse.help.toc ;
  • Is written using MediaWiki syntax ;
  • Has only one table of contents ; that lists all chapters of this documentation ;
  • Has the ant script that is necessary to produce HTML documentation from *.mediawiki source files ;
  • Is structured as follow:
<plugin_name>
  /html
    /<functionality>
      // Mediawiki and HTML source files
      /Images
        // Place all images in this directory
  build.xml
  plugin.xml
  about.html
  toc.xml
  build.properties
  
with <plugin_name> = org.polarsys.capella.<functionality>.doc

Ensure that:

  • plugin.xml contains the contribution to the org.eclipse.help.toc extension point
    • The contents of the contribution shall include the table of contents of the plugin, i.e. toc.xml
  • The root tag of toc.xml links to the anchor of the main table of contents PLUGINS_ROOT/org.polarsys.capella.doc/toc.xml#<anchor>

Contribute to the documentation modifying a Mediawiki file in the <html>/<functionnality> directory or create a new Mediawiki file in case you would like to add a new chapter. In case of a creation of a new Mediawiki file, do not forget to update the toc.xml in order to create a new Topic accordingly.

Before testing the contribution, the documentation first needs to be transformed into HTML.

To do so, right-click on the build.xml file and select Run as > External Tools Configuration.... Ensure that in JRE tab, the option Run in the same JRE as the workspace is selected otherwise tick it. Then press Run button. The generation starts and in logged in the console window.

When the generation ends with success, you can test it by launching Capella target platform then launching the Help menu.

Arcadia

A light introduction explaining the rationale and main concepts of Arcadia is now available for download on the website Arcadia page.

Communication

  • You can subscribe to the capella-dev@polarsys.org developers mailing list to be warned by Email about technical announcements.
  • In the forum, you can submit ideas, share knowledge with users and developers and ask questions about Capella.
  • The community page of Capella website also provides e-mail contact and support from Arcadia and Capella experts.
    • In this page you will also find links to LinkedIn and Twitter pages of Capella. Stay tuned!
  • Wikipedia now references Capella and Arcadia

Planning

Roadmap will be made available this year.

Quality Assessment

Capella continuous integration system has been enriched with SonarQube for managing code quality.

Moreover, PolarSys Maturity Assessment tool assesses quality in a larger way using quality model and metrics.

Access to Capella SonarQube results here.

Access to Capella Maturity Assessment results here.