Skip to main content

Eclipse 4diac Contribution Guidelines

Thank you for your interest in contributing to Eclipse 4diac™.

Eclipse 4diac is an open-source ecosystem for distributed industrial automation based on IEC 61499. The project is developed collaboratively by researchers, students, industrial users, and open-source contributors worldwide.

Getting Started

Our Philosophy

  • Everyone is Welcome: You do not need to be an expert or long-time community member to participate.

  • Diverse Contributions: We value code, documentation, testing, usability (UX), translations, and industrial feedback.

  • Step-by-Step Learning: New contributors are encouraged to start with small improvements and get to know the project step-by-step.

Code of Conduct

To ensure a welcoming and professional environment, all contributors and maintainers are expected to follow the Eclipse Community Code of Conduct. We are committed to making participation a harassment-free experience for everyone.

Need Help Before Contributing?

If you have questions or are unsure how to start, please ask first. The community is happy to help newcomers.

  • Ask Questions and Discuss Ideas:
    The preferred place for early discussions is the GitHub Discussions area of the specific repository ( 4diac IDE, 4diac FORTE, 4diac FBE, 4diac Documentation, 4diac Examples, or 4diac Website).

  • Discussion-First Approach:
    For larger changes, starting a discussion before implementation is strongly encouraged to align with project goals and avoid duplicated work.

  • Community Meetings:
    Joining our virtual community meetings is often the fastest way to find a suitable topic.

  • When to Open an Issue:
    Issues should be reserved for reproducible bugs, agreed-upon feature requests, or tracking active development. If you are unsure, start with a discussion.

Preparing to Contribute

Before you can contribute code or documentation, the Eclipse Foundation requires a few administrative steps to manage intellectual property correctly.

  1. Create an Eclipse Account
    You need an Eclipse Foundation account to sign legal agreements and track your contributions.

    • Register: Eclipse Registration Page

    • Important: Use the same email address for this account that you intend to use for your Git commit author information.

  2. Sign the Eclipse Contributor Agreement (ECA)
    The ECA is a digital agreement confirming you have the right to contribute the code you are submitting.

    • Sign here: Eclipse Contributor Agreement

    • You only need to do this once, and it covers all your contributions to any Eclipse Foundation project.

  3. Link your GitHub Account
    Since Eclipse 4diac uses GitHub for development, you must link your GitHub username to your Eclipse account so our automated tools can verify your ECA status.

    • Log in to your Eclipse Profile.

    • Enter your GitHub username in the "GitHub ID" field.

    • Save your changes.

Your First Contribution in 10 Minutes

The fastest way to contribute to Eclipse 4diac is by fixing typos or improving the documentation. GitHub allows you to do this directly in your browser, handling the technical "Git" background work for you.

Fast-Track: Web-Based Contributions

  1. Find a Page: Navigate to any file in our GitHub repositories (e.g., in the documentation or a README).

  2. Edit: Click the "Edit this file" (pencil icon) at the top right.

  3. Automatic Fork: If this is your first time, GitHub will notify you that it is creating a fork of the repository for you. This is normal—it’s just your personal workspace for the change.

  4. Modify: Make your changes directly in the web editor.

  5. Propose Changes: Scroll down, provide a short title for your change (e.g., "Fix typo in installation guide"), and click "Propose changes".

  6. Create Pull Request: On the next screen, click "Create pull request".

Tip
Don’t worry about the "Fork"

When you use the web editor, GitHub manages the fork and branches for you automatically. You don’t need to do anything on your local computer.
Note
Verification

Even for web edits, the ECA check will run. Ensure your GitHub account is linked to your Eclipse account as described in the previous section, otherwise the "Check" will fail on your Pull Request.

Standard Development Workflow

For larger contributions, such as code changes or complex documentation updates, you will need to work on your local machine. We follow the standard "Fork and Pull Request" model common on GitHub.

Important
Check Repository-Specific READMEs

While the Git workflow below is universal, the specific instructions for building, compiling, and running local tests are located in the README.md or CONTRIBUTING.md file of the individual repository you are working on. Always consult those files before starting your local development.
Note
Choose your tools

The examples below use Git Bash (command line) for clarity, but you are welcome to use any Git GUI (like GitHub Desktop, GitKraken, or the integration in Eclipse IDE/VS Code).

1. Fork and Clone

Instead of working directly on the main repositories, you create your own copy (a fork) and work there.

  1. Fork: Navigate to the specific Eclipse 4diac repository (e.g., 4diac-ide or 4diac-forte) on GitHub and click the "Fork" button.

  2. Clone: Clone your fork to your local machine:

    git clone https://github.com/your-username/4diac-ide.git

  3. Add Upstream: Connect your local repository to the original 4diac repository so you can pull the latest updates:

    git remote add upstream https://github.com/eclipse-4diac/4diac-ide.git
Tip
 If you are unsure which repository to fork, check the README of the individual projects or ask in the GitHub Discussions.

2. Branching

Always create a new branch for every contribution. This keeps your develop branch clean and allows you to work on multiple fixes at once.

  • Base Branch: In Eclipse 4diac, the primary development branch is

    • develop for 4diac IDE, 4diac FORTE, and 4diac FBE

    • main for 4diac Documentation, 4diac Examples, and 4diac Website

  • Create a Branch:

    git fetch upstream
git checkout -b my-fix-description upstream/develop

3. Commit Messages

We value a clean and readable commit history. Please follow these guidelines:

  • One Topic per Commit: Small, atomic commits are easier to review than one giant "Update everything" commit.

  • Format: Use a short, descriptive subject line (max 50 characters).

  • No Sign-off Required: You do not need to add a Signed-off-by line manually; our CI tools verify your ECA via your GitHub account.

  • Clean History: We encourage contributors to submit and maintain a clean commit history. This means:

    • Avoid "work in progress", "fix typo", or "review changes" commits in your final PR.

    • Use git commit --amend for small fixes to your last commit.

    • Use git rebase -i (interactive rebase) to squash or rename commits before pushing.

Commit Message Template

Short descriptive summary (max 50 chars)

Optional detailed explanation of what was changed and why.
Wrap lines at approximately 72 characters.

Example Commit Message

Handle referenced projects in library manager

Ensure referenced projects trigger a full build when manifests change.
Prevents inconsistent dependency states after updates.

4. Staying in Sync

If the original 4diac repository changes while you are working, you should update your branch to avoid merge conflicts.

git fetch upstream
git rebase upstream/develop  # Use upstream/main for documentation/examples/website

5. Submitting the Pull Request (PR)

Once your changes are ready and tested:

  1. Push to your fork:

    git push origin my-fix-description

  2. Open PR: Go to the 4diac repository on GitHub. You will usually see a yellow bar at the top suggesting to "Compare & pull request".

  3. Draft PRs: If your work is still in progress but you want early feedback, open the PR as a "Draft".

  4. Description: Briefly explain what you changed and why. If it fixes a bug, make sure the bug number is mentioned.
    Reference Issues: If your work relates to a GitHub Issue, include the reference the description of the pull request. By prefixing it with 'Closes', 'Fixes', or 'Resolves', Github will automatically close the issue when the PR is merged.

    Note
    		 Do not use a Github recognized keyword if the PR is only addressing parts of an issue!
Tip
 There is also usually a helpful message with a link when pushing from the command line or from Eclipse IDE. The link will start the PR creation process.

4. Updating a PR during Review

It is common for maintainers to ask for changes during the review process. To keep the history clean:

  1. Apply the requested changes locally.

  2. Incorporate them into the relevant existing commits using git commit --amend or an interactive rebase.

  3. Use git push --force to update our Pull Request.

Tip
 Rebase regularly against the base branch to avoid merge conflicts, especially for longer living PRs.
Tip
 A clean history makes it much easier for our maintainers to understand the logic of your changes and speeds up the merge process.

What Happens Next?

Once your PR is submitted, it enters the review phase:

  • CI Checks: Automated tests and ECA validation will run. If they fail, please check the logs and update your branch.

  • Code Review: A project committer will review your changes. We try to review PRs promptly, but please be patient as this is a community-driven project.

  • Feedback: It is completely normal to be asked to make changes. This is a collaborative process!

Coding Style & Testing

To maintain a high-quality codebase that is easy for everyone to read and maintain, we ask that you follow these technical guidelines.

1. Use the Provided Formatters

Each repository contains specific configuration files for code formatting (e.g., Eclipse Checkstyle, clang-format).

  • 4diac IDE: Follow the Eclipse Java Coding Conventions. Use the formatter profile found in the org.eclipse.4diac.ide repository.

  • 4diac FORTE: Follow the C++ style guide located in the org.eclipse.4diac.forte repository.

  • General: Always perform a "Format" on your changed files before committing.

Caution
 Existing projects are already set-up with the correct formating. Do not change them!

2. Copyright and License Headers

Every new source file must start with the Eclipse Public License 2.0 (EPL-2.0) header.

  • New Files: Use the template below.

  • Existing Files: If you make a significant change, add your name or your company’s name to the "Contributors" list and a short description of the change.

  • Official Reference: For detailed rules on copyright and attribution, please refer to the Eclipse Project Handbook - Copyright Guidelines.

Header Template
/*******************************************************************************
 * Copyright (c) {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
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *   {name} - initial API and implementation and/or description of change
 *******************************************************************************/

3. Testing Your Changes

We strive for high stability. A contribution is considered complete only when it includes proof that it works.

  • Run Existing Tests: Ensure your changes do not break existing functionality.

  • Add New Tests: If you add a new feature or fix a bug, include a corresponding test case (JUnit for 4diac IDE, BoostTest/Integration tests for 4diac FORTE).

  • Documentation: If your change affects the user interface or adds a new parameter, please update the corresponding documentation files.

Tip
 If you are unsure how to write a test for your specific change, mention it in your Pull Request or ask in GitHub Discussions. We are happy to guide you!

Rules on AI Usage for Contributions

We acknowledge that AI support is nowadays a state-of-the-art technique in software development. In order to maintain a healthy open source project in the era of AI tools, the human oversight of software development is gaining importance. Therefore

  • We expect that all code remains maintainable by humans.

  • Authors of PRs need to be able to personally explain their PRs in case of any questions during the review process.

  • Please note that you remain responsible for all your contributions. Therefore, please carefully check all guidelines and regulations as per the Eclipse Committer Handbook.

  • You should always gather feedback from the community first, especially if it is unclear who will maintain a feature.

  • Even if you need a change desperately for yourself, you shall open discussions, explain your requirements, and identify whether there is any other solutions that are already available.

Becoming a Committer

As you contribute more frequently, you may be invited to become a Project Committer. Committers have "write access" to the repositories and are responsible for the long-term health of the project.

1. Criteria for Election

We don’t just look at the amount of code; we look at the impact and sustainability of your work. An existing committer may nominate you if you meet the following:

  • Consistency: Significant contributions over a period of at least six months.

  • Sustainability: You intend to stay active in the project long-term. We generally do not elect committers whose work is tied to a time-limited project (e.g., a one-year thesis or internship).

  • Independence: Your contributions are of high enough quality that they can be merged with minimal core-team intervention.

  • Beyond Code: We value non-code contributions equally, such as extensive documentation refactoring, community support, or translation efforts.

  • Community Culture: You are an active participant in the community (GitHub Discussions, community meetings, or events).

  • Personal Connection: Usually, a personal meeting (virtual or physical) with existing committers occurs to ensure alignment with the project’s goals.

2. The Process

  1. Nomination: An existing committer nominates you based on the criteria above.

  2. Election: Existing committers vote on the nomination.

  3. Paperwork: The Eclipse Foundation validates your status and you sign the Committer Agreement.

  4. Official Reference: For the full legal details on elections and responsibilities, see the Eclipse Project Handbook - Committer Role.

3. Maintaining Committer Status

To keep the project moving, we expect committers to stay engaged.

  • Retaining Status: Even small contributions or community interactions (reviewing code, helping new users) are enough to remain active.

  • Retirement: If a committer is inactive for over a year and cannot be reached, or if future contributions are unlikely, the project may initiate a "Committer Retirement" to keep the active list representative of the current team.

Additional Resources

This section collects useful links for contributors who want to learn more about Eclipse 4diac, the community, and the development process.

Back to the top