PolarSys Software Development Plan For Capella And Kitalpha

Scope

Document Overview

This document fulfils the objective to provide to the open source community transparency regarding the organisation in place and the project management methods, in accordance with methodological requirements imposed by the Eclipse Development Process.

The SDP also details the development methodology that will be used. In particular:

• Organisation function rules in place for development
• Development life cycle and process that will be followed
• Techniques, methods, procedures and tools used
• Product and process quality assurance and quality management techniques, methods, procedures and tools used

The document contains all the fixed information relating to the organisation of the software development. Later, the document is updated further to any important change affecting its content or its scope, in particular regarding software engineering, organization of the development, etc.

Development Plan Organization

The top-level document describes the development process for the Eclipse Foundation. It is specialized by this document for in demanding engineering domains – such as aerospace, defence and security, transportation, energy, health care or telecommunications – safety-critical and embedded systems development that meet important requirements. This document respects the PolarSys Charter. It is generic and shall be instantiated by projects for specific rules.

Documents Cited

• Eclipse Development Process
• PolarSys Charter

Solution vs Component

Currently in progress...

PolarSys Solutions: Capella, Capella-studio Eclipse Components: EMF Diff/Merge, EGF

Domains Organization

Domains are identified as follow and will be detailed further in the document:

• Process domains:
  • Tests
  • Conception
  • Pilotage
  • Build
  • Release
  • Branches

• Transverse domains:
  • Intellectual property
  • Communication
  • Planning
  • Quality assessment
  • Requirements
  • Documentation

In the next parts, domains explanations will be subdivided into three parts:

• Objective: purpose of the domain
• Tooling: PolarSys infrastructure tooling available to fullfil the objective
• Rules: requirements to be respected along the domain

Requirements

Objective

Requirements specify constraints that shall be met or satisfied by the project.

Tooling

There is no requirement tool at Eclipse and PolarSys.

Requirements are tracked in by the PolarSys change management tool.

Rules

Each domain and component shall manage its own requirement list.

Change Management

Objective

Change management represents the task of tracking and controlling changes in the project. It establishes a logical way to organize and control changes.

Tooling

Bugzilla is the general-purpose bug tracker used within PolarSys. It can be accessed using https://polarsys.org/bugs/

A Bugzilla defect is assigned to someone or the "Project Inbox" (= unassigned). In order to be notified of inbox defects, in [1] or [2], add the inbox name in the "User Watching" section.

[1] eclipse: https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email [2] polarsys: https://polarsys.org/bugs/userprefs.cgi?tab=email

Rules

The project shall keep track of bug reports and feature requests. In this sense, no change in the software shall be allowed without the prior establishment of a Bugzilla ticket.

• First of all, any shall search for existing bugs. This action helps to prevent duplicates ;
• Description of the bug shall be as clear as possible ;
• Reporter shall provide a use case i.e. a way of reproducing the bug in the description ;
• Bug shall be cloned for each version it is detected in ;
• After analysis of a bug, if it appears that a COTS is involved, a bug on the COTS Bugzilla will be created and its reference reported into the bug description.

Note:

1. In case of an evolution, the reporter shall provide some requirements associated to the evolution in the description as plain-text or embedded in a text file as attachment to the bug in Bugzilla ;

2. For more information about possible fields on a bug, please refer to the following link: https://polarsys.org/bugs/page.cgi?id=fields.html#bug_status

Development

Overview

Development is done using Git, but all must first go through a Gerrit review.

Generic Development Platform

The standard environment advised to develop Capella is currently:

• Java 1.6 or more recent. Capella code is compliant (compilation and run) with both Java 1.6 and 1.7.
• Eclipse Modeling Tools IDE Juno or more recent, with following plugins installed (From the Marketplace):
  • EGit, an Eclipse Team provider for the Git version control system ;
  • Optional Mylyn connectors as described in this article:
    • Mylyn Tasks Connector: Bugzilla
    • Mylyn Context Connector: Eclipse IDE
    • Mylyn Builds Connector: Hudson/Jenkins
    • Mylyn Reviews Connector: Gerrit
    • Mylyn Version Connector: Git

Of course you are free to use any additional tools you want to make your development experience more pleasant for you. However, do not commit anything which adds new requirements without getting approval from the development team.

Getting the Sources

Obviously the first thing to do is get the source. This can be done using Git anonymously for consultation only or Gerrit for sources intended to be modified.

Note:

Clone of a given repository can be done using either Eclipse and EGit plugin or manually through command line.

Gerrit Configuration

For source that we are going to be modifying, we must use Gerrit. As with any git project you get the source by cloning the central repository that Gerrit is hosting.

But first of all, we need to configure Gerrit.

• Log into Gerrit - using your PolarSys account - at https://polarsys.org/r using "Sign In" button in the top right-hand corner
  • Username : the email address used during your Eclipse Account creation
  • Password : the password created during your Eclipse Account creation
• Generate an http password using dedicated button at https://polarsys.org/r/#/settings/http-password

Be sure to retain this password as it will serve to clone the project repository and make pushes.

Working Rules

By default, each Bugzilla bug correction should be done on a specific local branch.

Example:

• You want to correct a given bug bugid
• Create a branch locally from your Gerrit Capella repository clone directory:

cd <work_directory>

git checkout -b master bugfixes/'''bugid''' (without the quotes)

• At this stage, the contributor is ready to make a change and commit it locally.

Commit Messages Formatting

Make a commit when the code is ready to be shared with other users of the code - when it is relatively stable, safe, and properly tested. Always write a comment when committing something to the repository. Your comment should be brief and to the point, describing what was changed and possibly why.

[bugid] Bugzilla bugid summary

Longer description if needed, explaining the reasons of the change and its
impact, not paraphrasing the patch. The description should use wrapped line.

Bug: bugid
Change-Id: I00000000000000000000
Signed-off-by: author name

Recommandations:

• First line is 50 characters or less
• Then a blank line
• Remaining text should be wrapped at 72 characters
• Always mention the numeric bug id at the start of the first line (e.g. [432432])
• The first line should be short, this is not the place to give details.
• The Bug: bugid footer line is required
• The Change-Id: footer line is mandatory
• The Signed-off-by: footer line is mandatory.

Gerrit Review

Changes are uploaded to Gerrit but don’t actually become a part of the project until they’ve been reviewed and accepted. Indeed, it’s still desirable to have code reviewed to improve the quality and maintainability of the code. Once you’ve made your change and committed it locally it’s time to push it to Gerrit so that it can be reviewed. This is done with a git push to the Gerrit server.

The reviewer’s life starts at the code review. Gerrit’s default work-flow requires two checks before a change is accepted:

• Code-Review is someone looking at the code, ensuring it meets the project guidelines, intent etc.
• Verifying is checking that the code actually compiles, unit tests pass etc. There is a Gerrit Trigger Jenkins Plugin that will automatically build each uploaded change and update the verified score accordingly.

Once the reviewer has looked over the changes, he needs to complete reviewing the submission.

The label that the reviewer selects determines what can happen next. The +1 and -1 level are just an opinion where as the +2 and -2 levels are allowing or blocking the change. In order for a change to be accepted it must have at least one +2 and no -2 votes.

Regardless of what label is selected, once the Publish Comments button has been clicked, the cover message and any comments on the files become visible to all users.

Important:

In the case the change was not accepted so the creator needs to rework it. Re-working it is easy. All we need to do to upload a re-worked change is to push another commit that has the same Change-Id - than the initial change - in the message. Then push it to Gerrit in the same way as we did to create the review.

Release Engineering

Continuous Integration System

Hudson monitors the execution of repeated jobs, such as building versions of the solution. In a nutshell, it provides an easy-to-use so-called continuous integration system, making it easier to obtain a fresh build. It is available at:

https://ci.polarsys.org/

Hudson Jobs Organization

For a given solution/add-on to the solution, there is:

• One job for the master branch, i.e. the up-to-date development version of the solution/add-on ;
• One job for each branch of maintenance ;
• One job for Gerrit submissions.

Hudson Plugins

• Gerrit plugin ensuring efficient code reviews ;
• Promoted Builds plugin for releasing purposes.

Download Space / Storage

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

http://download.polarsys.org/

• Respects the download breakdown structure established in this document ;
• Filled using Hudson Promoted Builds plugin.

Download Space / Breakdown Structure

The general form of all Capella and Kitalpha downloads is the following:

http://download.polarsys.org/SOLUTION/PRODUCT/FORMAT/TYPE/VERSION/TARGET/

with:

ATTRIBUTE SOLUTION PRODUCT FORMAT TYPE VERSION TARGET

SAMPLE capella or kitalpha core, studio or addons platform, updates or dropins nightly, milestones or releases version number eclipse target platform, e.g. juno, kepler, luna, etc.

Note: In case of Capella addons, the addons directory contains subdirectories for each addon, e.g. system2subsystemtransition, docgenhtml, xmlpivot, etc.

Following is the list of acceptable build versions for each type of build and their meaning:

• Nightly builds correspond to the most recent successful builds from our Continuous Integration server. Version identifiers for nightly builds have the form

   x.y.z-NYYYYMMDD-HHMM 

  , where N stands for Nightly
  

• Milestone builds correspond to the milestones and released candidates. Version numbers for milestone builds have the form

   x.y.zMn 

  for milestones and

   x.y.xRCn 

  for release candidates
  

• Release builds correspond to official releases. Version numbers for release builds have the form

   x.y.z 

  
  

Third-party Dependencies

Currently in progress...

Both solutions depends on COTS (Components Of The Shell), to be built and run. Each COTS is available on the web and released, amongst others, as an update site for both development and stable release versions.

• Sirius
• EMF Diff/Merge
• Eclipse Modeling Components

Hudson Jobs Configuration

Hudson jobs shall be configured accordingly.

Testing

Solution tests description and report shall be written and referenced in order to ensure traceability between requirements of the solution and tests.

Documentation

Whenever a change occurs to the solution (change in a behaviour of a function, evolution of the solution, etc.) documentation shall be updated accordingly to describe this change.

Intellectual Property

References to Eclipse IP rules

References to the Eclipse IP rules:

• Eclipse Development Process: https://eclipse.org/projects/dev_process/development_process.php
• Eclipse Legeal Process: http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf
• IP Eclipse Policy: https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf

Eclipse Public License (EPL): https://www.eclipse.org/org/documents/epl-v10.php

PolarSys Tooling

The IP analysis is managed by the Eclipse IP Team. The Eclipse tracking tool is IPZilla (Bugzilla adapted to IP).

Regarding IP questions :

• Legal questions: license@eclipse.org
• Specific questions: emo-ip-team@eclipse.org

Communication

PolarSys provides different communication means to satisfy projects promotion:

• Wiki: https://polarsys.org/wiki/Main_Page
• Forum: http://polarsys.org/forums/
• Download page: http://download.polarsys.org/
• Website: http://www.polarsys.org/

PolarSys mailing list can be accessed at: https://polarsys.org/mailman/listinfo

Communication means shall be setup to provide efficient resources to both developers and interested third-parties.

For simple downloads (without a download page) documents shall be stored in the Wiki system (< 10 Mo).

Images and icons shall be stored and referred in the Wiki system.

Social networks shall be used in order to promote the project.

Planning

The roadmap and coordination actions such as meetings shall be established in Wiki or using a dedicated development methodology (Gantt, Agile, etc.) to specify:

• Main milestones and initial deadlines
• Report planning / Roadmap
• Meetings planning
• Other activities (Training sessions etc.)

Quality Assessment

PolarSys provides Hudson continuous integration system ensuring automatic testing and non-regression plus Gerrit frontend for code review.

Fixing bugs, ensuring code quality, providing clear documentation, promoting the project and getting users feedbacks is a suitable metric for quality assessment.

PolarSys Maturity Assessment Dashboard summarizes periodically several maturity-related metrics about projects. It is available here.

PolarSys SonarQube Dashboard summarizes for each continuous integration build the code quality. It is available here