|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
## 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”](#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](#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](#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](#2-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](#definition-of-done)
|
|
|
|
- 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](https://www.scrum.org/resources/blog/done-understanding-definition-done).
|
|
|
|
|
|
|
|
- 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](https://wiki.eclipse.org/images/3/3f/OpenPASS_Conventions.pdf) 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
|
|
|
|
|
|
|
|
## Guideline: Steps towards a new release
|
|
|
|
|
|
|
|
The `main` branch contains the last stable version of openPASS. Thus, the `main` branch is representing the official releases of openPASS and is being tagged accordingly (e.g. v0.7, v0.8, …). New features for the next version are developed in the `develop` branch before they are pushed to the `main` branch. To release a new version within the Eclipse infrastructure, certain steps must be followed:
|
|
|
|
|
|
|
|
1. Please read in the [Eclipse handbook](https://www.eclipse.org/projects/handbook/#release) the chapter about releases. The chapter contains detailed information about release reviews which should be performed for each major release. For a minor release it is sufficient to trigger a release review every year. After a successful release review for a minor release, an unlimited number of minor releases can be published for that year.
|
|
|
|
2. Release reviews are created as an issue in GitLab. As a reference, the release review for v0.8 can be found [here](https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/85).
|
|
|
|
3. After all relevant commits for the new version has been pushed to the `develop` branch, the `develop` branch may be only merged to the `main` branch when the CI is green.
|
|
|
|
4. After the merge, the new release is tagged with the according version number. The release date is set by tacking the version number.
|
|
|
|
4. After tagging a new release has to be created. The release is then associated to the tag, see https://gitlab.eclipse.org/eclipse/openpass/opSimulation/-/releases.
|
|
|
|
4. Update the link to the pre-built version on the webpage.
|
|
|
|
5. Afterwards, the documentation has to be updated.
|
|
|
|
|
|
|
|
## Update of Documentation
|
|
|
|
|
|
|
|
Step 1 is usually done by a committer. Step 2 should be done by the project lead.
|
|
|
|
|
|
|
|
### 1. Build documentation
|
|
|
|
- Clone sources of openPASS
|
|
|
|
- Installation of necessary tools (MSYS2, MinGW, etc.) https://www.eclipse.org/simopenpass/content/html/installation_guide/20_install_prerequisites.html
|
|
|
|
- Build documentation from MSYS2-MINGW64-shell
|
|
|
|
- mkdir build && cd build
|
|
|
|
- cmake -G "MinGW Makefiles" -DWITH_SIMCORE=OFF -DWITH_TESTS=OFF -DWITH_DOC=ON ..
|
|
|
|
- mingw32-make doc
|
|
|
|
- A "html" folder with the documentation is being created
|
|
|
|
|
|
|
|
### 2. Update documentation on the Eclipse server
|
|
|
|
The Git server hosting the documentation can be found here: https://git.eclipse.org/c/www.eclipse.org/openpass.git/.
|
|
|
|
|
|
|
|
- Clone sources of the documentation page: git clone ssh://username@git.eclipse.org:29418/www.eclipse.org/openpass.git
|
|
|
|
- Delete folder "<REPO>\content\html\“
|
|
|
|
- Add new documentation into "<REPO>\content\html\“
|
|
|
|
- Committ and push (directly into "master"):
|
|
|
|
- git add -A ("add everything")
|
|
|
|
- git commit -m "commit message"
|
|
|
|
- git push
|
|
|
|
- The documentation is automatically linked on the openPASS webpages |
|
|
\ No newline at end of file |
