Eclipse 4diac Logo design once use everywhere Open Source PLC Framework for
Industrial Automation & Control


Contributing to 4diac IDE or 4diac FORTE

Contribute to 4diac IDE or 4diac FORTE

The projects 4diac IDE and 4diac FORTE are stored as a Git repository in the Eclipse platform. It's open source, so you can download the project and you can even change things and improve it. But of course, it's not that simple, otherwise changes would be added without any control and could mess up the code. If you wish to report a bug, see the section Bug report.

Git repository

If you don't know what Git is, don't worry, we have all been there. Basically, Git is a distributed system that is used to control various versions of anything, but mostly of software code. The code is stored in a so-called repository which contains all files related to the software. After changing the code, instead of saving new files (fileV1, fileV2, fileFinalVersion, fileThisIsReallyTheFinalVersion, fileThisIsReallyTheFinalVersion2) in a new folder, you just "commit" the change and the changes are saved in the repository. To see older versions of the software, you go to the specific commit. The good thing about Git is the word "distributed" in its definition (I bet you didn't notice it). There's not only one repository, but anyone who wishes to contribute to the repository, copies the whole content of the repository to his/her computer and works there, changes there and commits there. Then, the user pushes to the repository where he/she copied from.

This is only the basic principle of Git, but it should give an idea of how it works. The step-by-step tutorial following below helps to set up Git for your first contributions. Plenty of information online helps to learn more about Git. Instead of starting from zero, I would recommend having a look at where you can download everything necessary to start contributing to any Git project. The documentation book about Git provides a good overview. Although the book is very long, you'll only need Chapters 1 and 2 to understand how Git works, and Chapter 3 to understand branches.

But I should warn you, young padawan, learning Git is hard. It's a very powerful tool, but it takes time to understand it. Simply, read the basics and follow the step-to-step guide. It is not necessary to try to understand everything before jumping to contributions. The best teacher is practice, so use 4diac FORTE or 4diac IDE as your example for practicing. You can't break anything. Git is bullet-proof.


You know how Git works, and have maybe already used it. But now, a new player is in the game: Gerrit. What is it? The information in Wikipedia helps, but putting it simple, it is the firewall of contributions. It's used by many platforms, including the Eclipse Foundation where the 4diac FORTE and 4diac IDE repositories are. When someone, a programmer with the best intentions, wants to contribute to 4diac FORTE code, he clones the Git repository, makes changes, commits and then pushes to the repository in the Eclipse Foundation. But of course, the change doesn't go directly to the repository. First, it has to be accepted by people in charge of 4diac FORTE or 4diac IDE. Therefore, the contributors push to Gerrit. Gerrit checks legal requirements, and then notifies the people responsible of 4diac FORTE that some new change has arrived. They then visit Gerrit, see the new change and can accept or deny it. Easy, right?

But to better understand Gerrit, it's better to work with it. We'll go step-by-step toward pushing code to Gerrit in order to contribute to 4diac FORTE.

Help 4diac IDE and 4diac FORTE - NOW!

As said before, we'll learn to contribute to 4diac FORTE step-by-step. However, if you want to contribute, you'll need to sign some legal documents online. If you don't wish to sign them, you can still get the code of 4diac FORTE and play with it.

Create an Eclipse account

First of all, you should create an Eclipse account. All commits that are created by Eclipse accounts without signed ECA will be rejected automatically. If you don't want to contribute, but just want to download the code and play around, skip to the next step.

To create the Eclipse account, simply go to and click "Create Account" on the top-right of the page. Then, just fill in the information to create an account. The email address indicated during account registration should also be used later in Git.

Submit bug reports

If you notice an issue related to Eclipse 4diac, you should report a bug via the following link: Bugzilla
You can report issues and suggestions for 4diac IDE, 4diac FORTE, the webpage,... after logging into your (new) Eclipse account. Follow the bug writing guidelines in order to allow other users to understand your issue. First, select the component that needs to be improved. Then, enter details about your system: the program version in use as well as your system. If the bug is not related to a certain operating system, choose All. The Summary will be the title of the bug and should be concise and descriptive. Further details are then added in the description field. Provide all information required to understand and possibly also reproduce a bug. Don't hesitate to also report minor issues.

Sign the ECA

The next step is to sign the ECA (Eclipse Contributor Agreement). This is mandatory in order to contribute to the projects. Go to the ECA page to read it and learn more about it. The ECA protects for example copyrights. Basically, when you sign it, you declare that you have full rights of every contributed change, which helps protecting intellectual property, including your own. If your contribution is part of your work at some company, you should talk first with your superior and the legal department to fully understand how to approach this.

The signing is done online after logging in to your account and selecting the "Eclipse Contributor Agreement". You need to check boxes and complete a textbox with "I AGREE". There's no tangible outcome. Eclipse stores your information together with the version of the ECA that you signed. You can print the ECA, but you won't get a certificate to print that says that you signed it. Your account will show that you have signed the ECA and there's a tool in Eclipse validating whether an account has signed it.

Use EGit to contribute: Preparations

The first example uses Eclipse and all the Git work will be done using EGit, normally installed automatically together with the Eclipse IDE. If you think GUI is for weaks and a real programmer should use command line, you can follow the instructions given below. Nevertheless, users without command line experience should stick to Eclipse.

  1. Get all required software

    The first thing to do is to get all the software. For 4diac FORTE download Eclipse for C++ and install it. The installation of the toolchain is described here. If you already have an Eclipse IDE but it's not configured for C++, you don't need to download another Eclipse, but only the C++ plugin. See a tutorial here. To install Eclipse IDE for developing 4diac IDE use this instruction. EGit should be installed automatically with your Eclipse, otherwise follow the steps here to install it.

  2. Configure EGit

    The first thing to do in EGit is to configure the user settings. The main items are the name and email address. This information is attached to your commits. To do that, just follow the simple steps in section 4.2 of the same link as above. In particular, open Window → Preferences → Team → Git → Configuration in Eclipse. Click "Add Entry..." to open a dialog box for a key-value pair. As a key enter email and as value enter the email address of your Eclipse account. Click "Add" and add another entry. The second entry consists of the key name and your full name as value. As you created the Eclipse account and signed the ECA in the previous step, you must use the same email address.

  3. Download 4diac FORTE or 4diac IDE repository

    In Eclipse, go to File → Import...→ Git → Projects from Git. Click Next and then select Clone URI. Next. Paste or in the URI field and then Next. Eclipse will connect to the repository and retrieve all its branches. Select all and click Next. The branches represent various development stages. For small updates/fixes to the current version, you can use the branch with the latest version number. Select the destination folder of the repository in your local machine and click Next. Wait while the repository is being downloaded. Click Next until the assistant is finished.

  4. Configure Gerrit

    Access the Gerrit page in Eclipse to manage your account details regarding Gerrit. Click Sign In in the upper-right corner. The username is the email address registered with your Eclipse account created in step 1.1. Log in with the password of your Eclipse account. Then, click on your name on the upper-right corner and choose Settings. There you can change your preferences concerning messages, follow projects, manage your password, ... You can push changes to Gerrit via SSH or https. In this example, we'll use https. SSH requires you to create public and private keys, which are stored in files. Eclipse use these files to connect to Gerrit. To know more about creating keys and configuring Eclipse, visit here, and then add the key in the SSH Public Keys setting in Gerrit.

    Go to HTTP Password in the Settings page of Gerrit, copy the username that appears and click Generate Password. You'll get a random long password that you'll use every time you want to push something to Gerrit. Go to Eclipse, right-click on the project → Team → Show in Repositories View. Then, expand Remotes, and right-click on origin → Gerrit Configuration.... In this step, you can choose ssh, https or another communication protocol. Choose https and paste your username from Gerrit to the field User. This will change the Push URI. In the Destination branch field, you should set the branch to push to. You can't push to a branch that doesn't exist in the Gerrit repository. Note that the destination branch begins with refs/for/. Click finish and see in the Repositories View that the Origin remote has changed the push URI. This means that when you send something to 4diac FORTE or 4diac IDE, it will send to Gerrit, but when you get something from it, you'll get it from the actual repository.

  5. (Optional) Look around and move between branches

    Now you have the newest 4diac FORTE or 4diac IDE code. After downloading the code of a project, look around first. Check the folders, read the documentation and readme files. Try to understand the folders and hierarchies.

    Right-click on a project in the Eclipse package explorer and select Team. There you find all possible commands for EGit. Team → Show in History will show you all the commits in the current branch. Normally, master is the main branch. If 4diac FORTE has another branch, and you want to work with it, you'll have to create a local branch that serves as reference of the original branch. That is, the Eclipse repository has a master branch (seen as origin/master), and for example a develop branch (seen as origin/develop). But you, locally, have only a master branch (seen as master). This local master is a reference to the origin/master and everything you change on it, will be then pushed to the origin/master. But if you want to work on the origin/develop branch, you'll need to create a local branch that references it. Details on branches can be found in the book mentioned above (chapter 3).

    Right-click on the project → Team → Switch To → Other.... There you'll see the local and remote branches. Select the remote branch you want to work on, for example origin/develop, and click Checkout. You'll get a message saying that you can watch the remote branch, or you can create a new branch locally to work on it. Click on "Checkout as New Local Branch" and then select a name for the local branch. Usually, the name of the original branch is copied, therefore, we'll call it develop (without the part "origin/") and click finish. Now you can switch between the branches, and the changes in each one will be reflected in the corresponding origin.

    The projects follows the workflow shown here. Basically, the master branch is used to release versions and the development of new stuff. You should always branch out from develop to work on something new.

Create contributions with Eclipse and EGit

After you downloaded the current code, you can start creating contributions.

  1. Find a bug to work on

    In order to contribute, you need to first find a bug to work on. All your changes should be related to a bug recorded in Bugzilla. You can look into the code and find something wrong or you can go to the list of bugs and see the ones that refer to the 4diac FORTE project. If you find an error, or even missing documentation, you should report the bug. In order to learn how to contribute you may want to edit some documentation. Maybe you find a typo or you'd like to add some details. Bug fixes are a metric that shows how the software development progresses. But be aware that when reporting a bug, it should have a clear way of fixing it. For a reported bug such as "Missing documentation", it is unclear when the bugfix is complete. Therefore, state for example which documentation is missing. Each bug in Bugzilla has an ID. Let's say we are working on bug number 123456.

  2. Make changes and prepare to commit

    Now you actually change the code. Open the files you want to change and edit them. Try to change less then 1000 lines in one commit in order to keep individual commits small. Larger edits can be split to several commits.

    Open the Git Staging View in Eclipse by going to Window → Show View → Other... → Git → Git Staging. In the Unstaged Changes you see all the files that were changed. Right-click on them and then Add to index. The selected files will be moved to Staged Changes.

  3. Commit the changes

    Committing changes is a very important step. The changes are first committed locally. The commit message is essential for pushing to Gerrit, you can find example messages below. In Gerrit, the commit is first verified to ensure that everything is fine and the changes are then accepted. The commit message is created in the Git Staging View and consists of three parts: the subject, the body and the footer. The three parts are separated by an empty line.

    • The subject must contain the number of the bug you are working on, listed between square brackets and followed by a short explanation of what the commit contains. Try to keep it shorter than 50 characters and, for better readability, start the message with a capital letter. Don't use a period at the end of the subject.

    • The body contains all the explanation of what was done. Use it to explain what and why, but not how.

    • The footer must have two parts (three if the Change-Id is needed):

      1. [ALWAYS] the link to the bug (Bug: )
      2. [ONLY TO OVERWRITE A COMMIT] the Change-Id field is used when you are adding the second commit to a change already pushed before (for example: Change-Id: If0b359ad15268ed179194cf5ad4fb5b2d09b3290). See NOTE 2 to know more about when to use it.
      3. [ALWAYS] the signing field (Signed-off-by: John Doe <johndoe@gmail>). Sign via the button showing a brush that is located above the Commit Message. The signature at the end is checked by Gerrit to verify that the committer has signed the ECA.

      NOTE: Empty lines are only allowed (and mandatory) between the subject, body and footer, not between the inner parts of the footer.

      NOTE 2: The Change-Id is not edited, when a commit is pushed to Gerrit for the first time (CommitOne). Gerrit generates the Change-Id. If CommitOne is rejected (erroneous code, missing information, etc.), you must revise the commit and amend (overwrite) the CommitOne. This generates CommitTwo. (You could also delete CommitOne completely, and create a new commit as CommitTwo). Remember that CommitTwo is a completely new commit. CommitTwo must have the Change-Id that Gerrit generated for CommitOne (Go to the Gerrit webpage, find the change of CommitOne and you'll see its Change-Id). When you push CommitTwo, it won't create a new entry in Gerrit. Instead, CommitTwo will appear below CommitOne on the same page. Now CommitTwo is waiting to be accepted.

    Example for CommitOne:

    • [123456] Change the initial value of temp variable

      The initial value of the temp variable was changed to 1 instead of zero because of weather conditions

      Signed-off-by: John Doe <johndoe@gmail>

    With the message done, click commit.

    Example for CommitTwo:

    • [123456] Change the initial value of temp variable

      The initial value of the temp variable was changed to 1 instead of zero because of weather conditions

      Change-Id: If0b359ad15268ed179194cf5ad4fb5b2d09b3290
      Signed-off-by: John Doe <johndoe@gmail>

    With the message done, click commit.

  4. Push the commit

    In the History View you can see the new commit you have just added. You can access this view by changing the tab from "Git Staging" to "History". So far, the commit is only stored locally, and noone else knows about it. It's time to push it to the repository in Eclipse. Right-click on your last commit → Push commit.... A dialog opens. With the configurations shown, you are trying to push to the develop branch of the Gerrit called refs/heads/develop. But, according to the Gerrit documentation, you should push to the magic branch named refs/for/[branch]. So, in the dialog, instead of the standard develop branch, change to refs/for/develop (instead of reds/heads/develop). Click next, and you'll be asked to introduce your https Gerrit password generated above. The push confirmation notifies that a new branch is being created. Don't worry about that, and click Finish. Enter the password again, and then the push should succeed. If anything fails, the error appears in the log.

Option 2: Git on command line

Use Git on the command line instead of EGit (this one is for the reckless, the knights of the keyboard and especially those afraid of mice).

The following instructions apply to Debian-based Linux systems such as LinuxMint or Ubuntu. It is assumed that you have already created your Eclipse account and signed the ECA as described above. Also the same rules for creating a bug report and working on the 4diac FORTE or 4diac IDE code apply. Of course, you can decide yourself which editor you want to use for coding. There are a lot of possibilities out there: VI, Emacs and many more. For code compilation and linking on a Linux system, the GNU compiler suite usually is the best choice. But the details on that won't be addressed here.

  1. Check and install Git command line tools

    If you are unsure whether the Git command line tools are already installed on your Linux box, you can enter the following command on Debian based distributions (e.g., LinuxMint, Ubuntu):

    johndoe@linuxmint ~/$ dpkg --get-selections | grep git

    If Git tools are already installed, you should get a reply such as:

    git  install
    git-core  install
    git-gui  install
    git-man  install
    git-review  install
    gitk  install

    If you don't see the output above, you'll need to install the Git tools with the following command:

    johndoe@linuxmint ~/$ sudo apt-get update && sudo apt-get install git
  2. Clone 4diac FORTE ord 4diac IDE repository to a directory of your choice

    First, create a directory in your own home directory and change to it. In my example, this is ⁄home⁄johndoe⁄develop⁄repos, but you can also choose another.

    johndoe@linuxmint ~/$ mkdir -p develop/repos
    johndoe@linuxmint ~/$ cd develop/repos

    Now it's time to clone the sources. In the following example the repository URL for 4diac FORTE is used. For 4diac IDE use instead.

    johndoe@linuxmint ~/develop/repos$ git clone
    Cloning into 'org.eclipse.4diac.forte'...
    remote: Counting objects: 1, done
    remote: Finding sources: 100% (1/1)
    Receiving objects: 100% (2283/2283), 1.27 MiB | 458.00 KiB/s, done.
    remote: Total 2283 (delta 0), reused 2283 (delta 0)
    Resolving deltas: 100% (1445/1445), done.
    Checking connectivity... done.

    After cloning, you can have a look at the branches of the repository, but first you'll have to change to the new 4diac FORTE source directory created automatically.

    johndoe@linuxmint ~/develop/repos$ cd org.eclipse.4diac.forte
    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git branch -a
    * master
    remotes/origin/HEAD → origin/master

    The "*" indicates the current active branch. Now switch to the "develop" branch, because this is the one, where the commits are supposed to go.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git checkout develop
    Branch develop set up to track remote branch develop from origin.
    Switched to a new branch 'develop'
  3. Configure your Git installation to work with Gerrit code review

    You should have already created your Eclipse account and Gerrit login, following the description above. Let's assume that your email account is and the login for Gerrit is jdoexy5. We'll set this in the git configuration first.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git config --global ""
    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git config --global "jdoexy5"

    Please note that git config --global settings are generally stored within a user-specific configuration file. This file is named .gitconfig and is stored in your own home directory and not in the FORTE repository. We'll now create an SSH public key which you need to upload to your Gerrit account later on.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ cd ~/.ssh
    johndoe@linuxmint ~/.ssh $ ssh-keygen -t rsa -C ""
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/johndoe/.ssh/id_rsa):
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/johndoe/.ssh/id_rsa.
    Your public key has been saved in /home/johndoe/.ssh/
    The key fingerprint is:

    You can just accept the default key file location by hitting the return key. The Eclipse foundation strongly recommends to use a passphrase for additional security. Now copy the newly created public SSH key to your Gerrit account at Display the contents of the public key file with the following command:

    johndoe@linuxmint ~/.ssh $ cat

    Copy everything displayed into your clipboard from the start (including ssh-rsa) to the end (including Now login to your Gerrit account at, click on the small arrow next to your user name displayed in the top-right corner and choose "Settings". In the menu on the left, choose "SSH Public Keys" and click on "Add key...". Now paste everything from the clipboard into the text field and click "Add". Your public key should appear in the list now. We'll check now, whether Gerrit is accepting your key properly. Let's do a small ssh login test.

    johndoe@linuxmint ~/.ssh $ ssh -p 29418
    The authenticity of host '[]:29418 ([]:29418)' can't be established.
    RSA key fingerprint is 1a:b6:dc:be:0e:1f:ab:01:70:aa:43:82:4d:54:51:37.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added '[]:29418,[]:29418' (RSA) to the list of known hosts.

    **** Welcome to Gerrit Code Review ****

    Hi John, you have successfully connected over SSH.

    Unfortunately, interactive shells are disabled.
    To clone a hosted Git repository, use:

    git clone ssh://

    Connection to closed.

    You'll have to configure the Gerrit Push URL within your Git configuration. Change to the hidden Git directory within the 4diac FORTE repository and edit the file named "config"

    johndoe@linuxmint ~/.ssh $ cd ..
    johndoe@linuxmint ~/ $ cd develop/repos/org.eclipse.4diac.forte/.git
    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte/.git $ nano config

    The following screenshot indicates the parts you need to add or change. Save and exit afterwards.

    Configure Gerrit Push URL
  4. Create your own commit message template (optional)

    You can create a commit message template file, which will be used everytime you do a new commit. You can add helpful comments, so that you don't forget important contents of the message or even add text, which should be part of every commit message. It's just up to you. Change to your home directory and create a new file called .git_commit_msg_template with your favorite text editor. Here I used nano for convenience.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte/.git $ cd /home/johndoe
    johndoe@linuxmint ~/ $ nano .git_commit_msg_template

    The following screenshot shows some example content. See above for more details of the message guide

    Example of commit message template contents
  5. Do your first command line commit

    A new commit should always be in relation to a bug in Bugzilla as already mentioned above. A bug can also add new functionality to 4diac FORTE. A single commit should not contain more than 1000 lines of code (yes, you are right, this was already mentioned above, but you can never emphasize this too often). A good approach to check whether something was changed in your local 4diac FORTE sources and needs to be committed is the git status command. You should change to your local 4diac FORTE Git repository first.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git status
    On branch develop
    Your branch is up-to-date with 'origin/develop'.

    Untracked files:
    (use "git add file..." to include in what will be committed)


    nothing added to commit but untracked files present (use "git add" to track)

    In the example above, I only added an empty directory, which is now recognized by Git as untracked. If you want to add some new files, just copy them to your local 4diac FORTE repository or edit existing files. Git will recognize the changes and you'll see the files with the "git status" command. To be able to commit anything, the respective files need to be added first. In this way, the files will be moved to the so called staging area. So flex your fingers and add properly.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git add src/modules/conmeleon_c1/util
    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git status
    On branch develop
    Your branch is up-to-date with 'origin/develop'.

    Changes to be committed:
    (use "git reset HEAD file..." to unstage)

    new file: src/modules/conmeleon_c1/util/fileres.cpp
    new file: src/modules/conmeleon_c1/util/fileres.h
    new file: src/modules/conmeleon_c1/util/uncopyable.h

    Untracked files:
    (use "git add file..." to include in what will be committed)


    Now we do the commit itself. Don't forget the -s option for automatic sign-off which is required by the org.eclipse.4diac.forte project and to follow the message guide if you didn't do it already as a template. After the git commit command the default editor will be opened with your commit message template and you have to enter the message information (Bugzilla ID, what was changed and why and the URL to the bugzilla entry).

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git commit -s
    [develop 3a8de79] [495477] Add conmeleon support to forte
    3 files changed, 272 insertions(+)
    create mode 100644 src/modules/conmeleon_c1/util/fileres.cpp
    create mode 100644 src/modules/conmeleon_c1/util/fileres.h
    create mode 100644 src/modules/conmeleon_c1/util/uncopyable.h

    So far so good. This was not really a big deal, was it? The next step is pushing to Gerrit code review and then your new code will be scrutinized by the never sleeping eyes of the project code reviewer.

  6. Push to Gerrit

    This is not difficult, if you followed the steps above. You are just a single command away from finishing.

    johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git push origin HEAD:refs/for/develop
    Password for '':
    Counting objects: 38, done.
    Delta compression using up to 2 threads.
    Compressing objects: 100% (8/8), done.
    Writing objects: 100% (9/9), 3.84 KiB | 0 bytes/s, done.
    Total 9 (delta 3), reused 0 (delta 0)
    remote: Resolving deltas: 100% (3/3)
    remote: Processing changes: new: 1, refs: 1, done
    remote: ----------
    remote: Reviewing commit: 3a8de79f
    remote: Authored by: jdoexy5 (
    remote: The author is not a committer on the project.
    remote: The author has a current Contributor License Agreement (CLA) on file.
    remote: The author has "signed-off" on the contribution.
    remote: This commit passes Eclipse validation.
    remote: New Changes:
    remote: [495477] Add conmeleon support to forte
    * [new branch] HEAD → refs/for/develop

    You did it, good job! Now it's the reviewer's turn and you'll see his or her comments in the Gerrit code review webpage.

Things to keep in mind for contributions:

  • When creating new files for the project, add the copyright terms at the beginning. Following the year of modification, add the name. Additionally, add your name below "Contributors", together with a short description of your contribution. Example code:
    {year} {owner}[ and others]

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License 2.0 which is available at

    SPDX-License-Identifier: EPL-2.0

    {name} - initial API and implementation

  • Always contribute to a bug.

  • Put the bug number between brackets in the subject of the commit message, and the link to the bug in the footer.

  • Don't forget to sign the commit.

  • Use the Gerrit website to see the commits you pushed and their status.

  • Don't be afraid of contributing code.

  • Use the forums in case of doubt.

  • Find more info here.

Where to go from here?

Back to Development index:

Development Index

If you want to go back to the Start Here page, we leave you here a fast access:

Start Here page

Or Go to top