## 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

- Keeping in sync with the official Eclipse ESCET GitLab repository

- How to become a committer

### 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):

- 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:

- Eclipse Foundation Project Handbook

- Git Commit Records

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:

  - `git remote add upstream https://gitlab.eclipse.org/eclipse/escet/escet.git`

- 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:

- Barriers for Entry (Wayne Beaton, Director of Open Source Projects at Eclipse Foundation)

- Make This Person We Hired a Committer (Wayne Beaton, Director of Open Source Projects at Eclipse Foundation)