Contributing

Interested in contributing to the Eclipse ESCET project? Contributions are always welcome!

The following information may help you get started:

How to contribute to Eclipse ESCET

It is often a good idea to first discuss your contribution with the project’s community and committers, before creating the actual code (e.g. patches), documentation, etc of your contribution. Discussions can take place via an issue in the issue tracker, or on the project’s 'dev' list.

To contribute your actual contribution, e.g. code, documentation, examples, or anything else to the project, please make sure an issue already exists or create a new issue for it in the issue tracker.

To create issues, reply to issues, contribute patches and merge requests, etc, you need an Eclipse Foundation account. It can easily be created at https://accounts.eclipse.org/user/register.

The easiest way to contribute the actual contribution, is to use GitLab:

  • Create a fork of the official Eclipse ESCET GitLab repository under your own account:

    • Navigate to https://gitlab.eclipse.org/eclipse/escet/escet.

    • If not signed in, click Sign in at the top-right of the page, and sign in with your Eclipse Foundation account. Then navigate back to https://gitlab.eclipse.org/eclipse/escet/escet.

    • Click the Fork button at the top-right of the page, and create your fork:

      • For the Project name and Project slug, use escet.

      • For the Project URL select your Eclipse Foundation account username as namespace.

      • For the Project visibility select Public.

      • Click Fork project.

    • Ensure the Eclipse ESCET bot has permissions to your fork. This enables the build server to communicate the build status of your merge requests to your forked repository. It also enables that your merge requests can be merged into the official Eclipse ESCET GitLab repository:

      • Navigate to https://gitlab.eclipse.org/<username>/escet/-/project_members, with <username> replaced by your Eclipse Foundation account username.

      • Click Invite members.

      • For Username or email address type escet-bot, and select the escet bot user from the list.

      • For Select a role select Developer.

      • Click Invite to finish adding the bot.

  • Set up a development environment to work on your contribution:

    • You can find your fork at https://gitlab.eclipse.org/<username>/escet, with <username> replaced by your Eclipse Foundation account username.

    • Click the Clone button near the top-right of the page and observe the https URL.

    • Follow the development environment setup instructions to set up a properly configured development environment. You need the https URL of your fork for this.

  • Make your changes in the forked repository under your own account:

    • If you followed the development environment setup instructions, your development environment contains a clone of your forked repository, all set up to commit and push to the upstream forked repository.

    • Make your changes in a branch of your forked repository, rather than in develop. This allows you to work on multiple contributions at once. It also allows syncing back changes from the official Eclipse ESCET develop branch to the develop branch of your forked repository, while you’re working in a branch.

      To create branches in your fork, navigate to https://gitlab.eclipse.org/<username>/escet/-/branches, with <username> replaced by your Eclipse Foundation account username. There click New branch to create a new branch from develop.

    • Please start each commit message with the issue number, e.g. #NNN Commit summary. for issue NNN. See our development process for more information.

    • To push a commit, you’ll be asked for your credentials. Assuming you have 2-factor authentication (2FA) enabled for your Eclipse Foundation GitLab account, use your GitLab username and a GitLab access token (not your password).

  • Once you’ve finished work on your contribution, create a merge request for it:

    • Navigate to https://gitlab.eclipse.org/<username>/escet/-/branches, with <username> replaced by your Eclipse Foundation account username.

    • Click Merge request next to the branch for which you which to create the merge request.

    • On the New Merge Request page that is shown, click on Change branches.

    • Change for Target branch the repository to eclipse/escet/escet (the official Eclipse ESCET GitLab repository).

    • As target branch typically develop should be selected.

    • Your forked repository (e.g. <username>/escet) and branch should already be selected for Source branch.

    • Click Compare branches and continue to confirm.

    • Select an appropriate title. Ideally it starts with the issue number, similar to the first line of a commit message.

    • Describe your changes under Description.

    • Make sure Allow commits from members who can merge to the target branch is enabled. This allows collaboration with the Eclipse ESCET committers on the merge request.

    • You may optionally make other changes to the merge request.

    • Click Submit merge request to submit the merge request to the Eclipse ESCET project committers for review.

Before your contribution can be accepted by the project team, you must electronically sign the Eclipse Contributor Agreement (ECA):

The non-committer that authored the commit, must have an Eclipse Foundation Account and must have a signed Eclipse Contributor Agreement (ECA) on file. The name and email address of the commits must match the corresponding information on the Eclipse Foundation Account. For more information, including the specific format of commit messages, please see the Eclipse Foundation Project Handbook:

A contribution by a non-committer will be reviewed by the project committers. This includes adherence to the project’s coding standards. Discussions regarding the contribution will typically take place in the associated merge request (or issue).

Align with the project committers on who will address the review feedback. If you address the feedback yourself, you can commit and push additional commits to the source branch of the merge request. These will then automatically be picked up by GitLab. Once the committers agree with the contribution, they will merge the contribution into the project’s official Git repository.

Remember that contributions are always welcome, and contributions don’t have to be perfect. The project’s developers can help to improve your contribution. If you need any help regarding the content of your contribution, the steps above, or anything else, just ask the project’s developers via the issue or the project’s 'dev' list.

See for more information our development process.

Keeping in sync with the official Eclipse ESCET GitLab repository

If you’ve set up a development environment for your forked repository, it will at some point get out of sync with new developments on the official Eclipse ESCET GitLab repository. To sync those changes to your forked repository and to the local clone of your forked repository, follow these steps:

  • Navigate in a command prompt or shell to your local Git clone of your forked repository. It is typically located in the git/escet directory within the directory that contains your development environment.

  • Add the official Eclipse ESCET GitLab repository as upstream remote repository to your local repository, by executing:

  • You now have upstream as a remote repository that connects to the official Eclipse ESCET GitLab repository. You will also still have origin as a remote repository that connects to your forked repository on the Eclipse Foundation GitLab server. Adding the upstream remote repository is a one-time only step. The remaining steps can be repeated whenever desired, to resync your develop branch to the develop branch of the official Eclipse ESCET GitLab repository.

  • Locally, switch to the develop branch, by executing:

    • git checkout develop

  • Fetch all changes from the upstream repository, by executing:

    • git fetch upstream

  • Update your local develop branch with the changes from the develop branch of the upstream repository, by executing:

    • git pull upstream develop

  • Push the changes to your forked repository on the Eclipse Foundation GitLab server, by executing:

    • git push origin develop

We recommend that you remove feature branches once your contribution has been accepted into the official Eclipse ESCET GitLab repository’s develop branch. Then, use these steps to resync your local develop branch and the develop branch of your forked repository with your own contribution. You are then back in sync and ready to start work on your next contribution. Using this process it is also possible to work on multiple contributions at once, via separate feature branches.

How to become a committer

The Eclipse Foundation operates on the principle of meritocracy. Anybody can contribute to Eclipse ESCET as a contributor. But the more that somebody contributes, the more responsibility they will earn. To earn committer status, a contributor must demonstrate that they understand their responsibilities, both as an Eclipse Foundation committer in general and as a committer for the project in particular.

A contributor can be elected to become a committer. This starts with a nomination by an existing committer. For further details on the process, see the Committer Elections section of the Eclipse Foundation Project Handbook.

Each project can define the criteria that are considered for nominations. The criteria for the Eclipse ESCET project are as follows:

  • Demonstrate a good grasp of the Eclipse Foundation Development Process, including the Eclipse Foundation Intellectual Property Policy.

  • Provide several high-quality non-trivial contributions that demonstrate a good grasp of the code base, its structure and the underlying concepts.

  • Demonstrate a good grasp of the Eclipse ESCET way of working, including use of issues, merge requests, code style, build, tests, etc.

  • Demonstrate the ability to work together with the current committers and the wider community, in a positive, open and transparent manner.

The more of these criteria that have been shown the better, but it is not a requirement to show all of these to the same degree. In the end it is up to the existing committers to judge whether enough merit has been demonstrated to warrant a nomination.

The Eclipse Foundation also requires that nominations are supported by public evidence that demonstrates the merit. This ensures that the process of electing new committers is transparent. Furthermore, nominations and elections must be open, in that anybody that shows merit should be considered equally for nominations. It must definitely not be based on employment status.

Obviously, the contributor must be willing and able to become a committer, and there must be an outlook that the contributor will remain active in the future.

For more information, see also the following blog posts: