Skip to content
Snippets Groups Projects

Development Process

Last edited by Arun Das

Introduction

OpenPASS as an open source project grows through contributions from the working group and third parties. However, these contributions must follow certain rules to maintain consistent and high quality solutions. Consequently, anybody who wants to contribute to openPASS should stick to these rules. In the following, the process from the creation of an issue over solving it to the final merge is shown. Besides that, GitLab rules, further definitions and guidelines regarding the development process are explained.

Process Overview

The development involves several parties within and outside of the working group. The individual steps for contributions are shown in the following image and are described below.

Copy following mermaid code into the live editor https://mermaid.live/:

flowchart TD
    REQ(Requestor) -->|"create an issue (according to DoR)"| Issue
    PM(Product Manager) --> |check DoR <br> track progress of issue|Issue
    CW(Contributors and WG members) --> |technical review <br> discussion on the issue| Issue
    C(Contributor) --> |pick and selfassign issue <br> implementation of issue|Issue
    A(Assignee) --> |"creates Merge Request according to DoD"|MR(Merge Request)
    REV(Reviewer) --> |code review|MR
    CI(CI) --> |automated verification on the Continuous Integration Toolchain|MR
    COM(Committer) --> |closes Merge Request|MR

Description of Process Steps

  1. Requestor --> Create an Issue

    An issue is an element in GitLab to collaborate on ideas, solve problems, and plan work. When creating an issue the requestor describes the issue as detailed as possible following the guideline “Definition of Ready”. A requestor can be both an internal openPASS WG member or an external person.

  2. Product Manager --> Check the DoR and track the progress of an issue

    The product manager is responsible to check the issues for completeness and accordance to the DoR. The product manager tracks the progress on a regular basis.

  3. Contributors and WG members --> Technical review and discussion on the issue

    Clarifications and discussions among the requestor, contributors and other stakeholders take place directly within the issue. Special focus is put on technical aspects and solution approaches.

  4. Contributor --> Pick and self-assign the issue and implement the solution

    A contributor (committer, WG member, or external contributor) takes over the resolution of the issue. After self-assigning the issue the contributor (now assignee) is responsible for implementing the solution. The assignee sets the label Status::WIP as soon as work on the issue has started.

    In some cases, re-assigning or un-assigning an issue might be needed during the implementation phase.

  5. Assignee --> Creates Merge Request (MR) according to DoD

    In the next step, the assignee creates a merge request. If the implementation has not yet been finished but the assignee would like to get a review, the MR can be created as a draft (according label WIP needs to be set). A final MR has to comply with the Definition of Done. When creating a MR the CI is automatically triggered.

    The description of the MR should contain a link to the corresponding issue. In case a feature has already been implemented without an according issue, the issue needs to be created and linked along with the MR. The issue needs to describe the motivation, feature gap and requirements regarding the solution. This also holds for bugfixes.

  6. Reviewer --> Do Code Review on MR

    The reviewer reviews the code of the MR according to the review process. Each MR has to be reviewed by at leasts one reviewer but can potentially be reviewed by multiple reviewers as well. Feedback and comments are made directly within the MR. Once all required changes have been made, the reviewer approves the MR for merging. The label Status::Ready for merge is being set by the reviewer.

  7. CI --> Automated Verification on the Continuous Integration Toolchain

    The CI is automatically triggered after a MR is created or updated. For more details on the automated processes check out the description of the CI.

  8. Committer --> Closes the MR

    Once the label Status::ready to merge is set and the CI has run successfully, a committer merges the MR into the according target branch. The committer closes the according issue by referring to the corresponding MR.

Note: Along to the described process, the product manager continuously provides guidance for the developments and discussions. Especially setting the correct labels for issues and merge requests is supervised and supported by the product manager.

Definition of Ready (DoR)

Each issue in GitLab has to comply with the Definition of Ready (DoR). The requestor who creates an issue can use the following points as guideline for creating an issue:

Assignee: Name an assignee if already known (e.g. self-assign the issue). Otherwise leave field blank for later assignment.

Epic: Link to an epic if the issue belongs to a large topic.

Milestone: If the solution of the issue is planed for a specific release, specify the target release version (e.g. v0.11). Otherwise set the default milestone vx.x.

Iteration: Not needed

Time tracking: Not needed

Due date: Not needed

Labels: Different categories of labels have been created to allow for a detailed description of the issue on top level.

Type:

  • Type::Bug: issue reports a bug or defect
  • Type::Feature Request: a new feature is requested
  • Type::Incident: non-code related issues like security stuff, leaked credentials, legal problems or violations against the Eclipse process, git "accidents" etc.

Status:

  • No status label means that currently nobody is working on the issue
  • Status::Work in progress: assignee is working on the issue
  • Status::Under review: a MR has been created and is being reviewed (should be set by the assignee)
  • Status::Ready for merge: review has been completed successfully and the MR is ready to be merged (should be set by the reviewer).

Domain: Specifies the relevant parts of openPASS which will be affected by the issue (multiple can be set at the same time). Available labels are:

  • Domain::Core
  • Domain::Build
  • Domain::GUI
  • Domain::Documentation
  • Domain::Test
  • Domain:: Regression
  • Domain::Utils
  • Domain::CI
  • Domain::Configuration

Misc:

  • Misc::Help Wanted: Issue creator needs input from the openPASS WG. A discussion on a specific topic is needed.
  • Misc::Decision needed: A decision is needed.

Weight: Not needed

Health status: Not needed

Rules for commit messages

A uniform convention for writing commit messages is currently being defined. Up until then, the following elements shall be considered:

  • Affected part of the code (i.e. the modified component or module)
  • Short documentation on the new feature or resolution of a bug
  • ID of the resolved issue in GitLab

Review Process

Once the assignee has created a MR the review process starts. A review is a systematic examination of an implementation by one or multiple people with the main goal of ensuring consistent and error-free code along with high quality implementations. Each review is combined from a manual code review along with automated checks on a continuous integration toolchain.

1. Manual Code Review

At least one manual review is required before a merge can be conducted. The following checks shall be performed:

  • Fulfillment of of all DoDs
  • Meaningful commit message
  • Implementation complies with general design ideas of openPASS
  • Spell checking of code and documentation

2. Automated Checks on Continuous Integration (CI) Toolchain

A Jenkins continuous integration pipeline is configured to automatically check branches and merge requests. Any change that is being pushed to a branch will trigger the execution of the configured pipeline. Each pipeline execution builds openPASS and the documentation. Further, Unit-, Integration- and EndToEnd-tests are executed. The steps are executed on a Windows and a Linux machine in parallel. The whole pipeline configuration can be found in the repository under utils/ci.

Merge requests automatically trigger two pipeline executions, one for the head and one for the merge.

The CI is publicly available under https://ci.eclipse.org/openpass/. More insights on the individual steps can be found in the stage view of the branches or merge requests. Further, each build generates a set of artifacts for further usage or debugging in case of errors. Part of that are the built binaries of openPASS and the results of the EndToEnd-test simulations along with the according report.

Definition of Done (DoD)

The DoD defines all requirements that need to be fulfilled for a contribution. A general introduction of the concept of Definition of Done can be found here.

  • A merge request has been created and refers to the according issue
  • The CI reports success on the automated build and test
  • Code review and according code changes have been done
  • The coding guideline is followed
  • Maintenance of documentation (inline code documentation and user documentation in rst/sphinx)
  • Test coverage of new and adapted code with unit tests (line coverage of >= 80%)
  • New E2E tests are set up for implemented feature if applicable
  • Copyright Headers are updated
  • Contribution Questionnaires (CQ) for new third party dependencies are created and approved
  • Code has been formatted automatically using clang format

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent