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.
PolarSys Software Development Plan For Capella And Kitalpha
Contents
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
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):
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 |
SAMPLE capella or kitalpha |
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 andx.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