# Contributing Patches

## Using Gerrit

EGit and JGit projects are using Gerrit Code Review for Git based patch submission and review.

Both projects accept contributions only via Gerrit. Please do not send patches by e-mail. Although both projects are mirrored to Github, EGit and JGit also cannot accept Github pull requests.

Migration from git.eclipse.org to eclipse.gerrithub.io

Since the Eclipse Foundation decided to deprecate their Gerrit server EGit and JGit migrated their repositories to GerritHub at https://eclipse.gerrithub.io. The migration to GerritHub was completed on Nov 21, 2023.

GerritHub combines Gerrit for code review and GitHub for authentication, issue tracking and browsing repositories.

- Find the Eclipse tenant of GerritHub here: https://eclipse.gerrithub.io

### User Account

- In order to contribute you need an Eclipse user account on eclipse.org
  - On creation of a new account you must agree to the Contributor Agreement.
- For login to GerritHub and GitHub you need a GitHub account.
  - Associate your GitHub username with your Eclipse Account
    - Edit your Eclipse account: login and click "Edit my account"
    - Set your GitHub username at the bottom of the page "Personal Information".
- If you are a project committer you will get an invitation to join the project's GitHub organization
  - Modifications of Eclipse user accounts are replicated every 2-3 hours to GitHub, i.e. it could take a few hours to get this invitation
  - You can check in GitHub settings if you are a member of the project's GitHub organization

### Login to GerritHub and OAuth access to GitHub

GerritHub uses github.com for authentication. Permissions are granted to GitHub teams which are configured by Eclipse Foundation in the GitHub organisations eclipse-egit and eclipse-jgit.

For that it needs an GitHub OAuth scope granting read access to GerritHub:

1. Login to https://eclipse.gerrithub.io by clicking "GitHub Sign-in"

2. On the first login GerritHub requests authorization for read access to GitHub.

- Reviewer: Review other people's changes using only your e-mail identity
- Contributor: Contribute and upload changes to JGit/EGit
- ProjectCommitter: Contribute to JGit/EGit as a committer
- EclipseStaff: Administrate Eclipse Foundation Projects, import new projects from GitHub to GerritHub

If you are an EGit/JGit committer or Eclipse Foundation administrator

- Request "organisation access" for the GitHub organisation eclipse-egit / eclipse-jgit.
- This request needs to be approved by an Eclipse Foundation administrator.
- It grants GerritHub read access to your membership in GitHub teams of the organisation used to check your committer / administrator status.

All users need to click "Authorize gerritforge-ltd" which want to

- participate in code review (contributors, committers)
- contribute changes (contributors, committers)
- administrate projects in eclipse.gerrithub.io (administrators)

The initial scope selection done at login is stored as a cookie.

You are redirected to https://eclipse.gerrithub.io

If you are a committer or administrator you can check if access to github organisations was granted:

- Open https://eclipse.gerrithub.io/settings/#Groups
- If your request was approved you see groups of the GitHub organisation (e.g. "github/eclipse-jgit/technology-jgit-committers").

- If the approval of your request takes too long open a ticket on the Eclipse helpdesk.

3. If you want to change your access scope

- click "GitHub > Scope"

- and select the access scope you want to use on GerritHub.

4. Click "login" to authenticate.

- GitHub redirection after login may take up to 30 seconds to complete.
- Be patient, just wait and do not refresh the page until you are redirected to eclipse.gerrithub.io.

Git over SSH

When accessing GerritHub over SSH from git or EGit

- use your GitHub username
- upload your public SSH key to your GitHub account here
- Import the keys to GerritHub
  - Login to https://eclipse.gerrithub.io and click "GitHub > Profile"
  - Select the keys you want and then press "Next".
- Gerrit SSH URL: `ssh://username@eclipse.gerrithub.io:29418/eclipse-egit/egit`
- Find all the repositories here

Git over HTTPS

When accessing GerritHub over HTTPS from git or EGit

- use your GitHub username and the Gerrit HTTP password which can be generated here
- Gerrit HTTPS URL: `https://<username>@eclipse.gerrithub.io/a/eclipse-egit/egit`
- Find all the repositories here

### SSH Keys

- Add one or more public SSH keys to your GitHub account here.
- If you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you use a passphrase.
- Generating SSH key pair on command line

    ssh-keygen -t ed25519 -C "your_email@youremail.com"

- Execute SSH once to accept the host key

    ssh -p 29418 username@eclipse.gerrithub.io

- Generating SSH key pair in Eclipse

### Legal Paperwork

Before your first contribution can be accepted, you need to electronically sign the Eclipse Contributor Agreement(ECA). The ECA is good for three years. Find more information in the ECA FAQ.

Minimally, all Git commits you contribute must have the following:

- A single line summary in the comment field, followed by a more detailed descriptive paragraph;
- Your credentials (email address) captured in the "Author" field
- In addition ensure that the contributed code is licensed under the project license (EPL 2.0 for EGit and EDL 1.0 for JGit). This is done by putting a copyright and license header into every new java file. See other existing project source files for the correct content.

With a valid ECA on file and the copyright and license header in place, we will be able to accept small patches (<1000 LoC) immediately. For larger patches, we will also have to create a contribution questionnaire for review by the Eclipse IP team, but this usually doesn't require additional actions from you.

To verify whether a contribution requires a CQ, use one of the following git commands to check:

- If it's committed: `git log --shortstat`
- If not committed: `git diff --stat`

These commands tell you the number of insertions(+), and deletions(-). If the total number of lines inserted (e.g. added) in a contribution is greater than 1000 (yes, this includes comments) then a CQ is required.

Find more details about how to contribute in Contributing via Git (for contributors) and Handling Git Contributions (for committers).

### Doing Code Reviews with Gerrit

- Visit the Eclipse tenant of GerritHub to start reviewing,
- Register to watch projects if you want to be notified by email on new or updated changes pushed for review
- Adjust your Gerrit settings to customize it to your needs
- See the Gerrit user guide for more information about using Gerrit.
- The EGit tutorial walks you through the basic steps of working with Gerrit and EGit.
- Use Gerrit queries to filter the review list for changes you are interested in:
  - EGit changes pending in review
  - JGit changes pending in review

### Using Gerrit with git command line:

- Upload your patch from Git to the target project:

JGit

    git push ssh://username@eclipse.gerrithub.io:29418/eclipse-jgit/jgit.git HEAD:refs/for/master

EGit

    git push ssh://username@eclipse.gerrithub.io:29418/eclipse-egit/egit.git HEAD:refs/for/master

- Visit the Eclipse tenant of GerritHub to start reviewing

#### Adding a dedicated remote

Since git can have multiple remotes, you can define one to be used to refer to Gerrit to save typing. Inside a previously checked-out repository you can run:

    cd path/to/jgit
    git config remote.review.url ssh://username@eclipse.gerrithub.io:29418/eclipse-jgit/jgit.git
    git config remote.review.push HEAD:refs/for/master

    cd path/to/egit
    git config remote.review.url ssh://username@eclipse.gerrithub.io:29418/eclipse-egit/egit.git
    git config remote.review.push HEAD:refs/for/master

You can now submit review requests from either repository using:

    git push review

### Using Gerrit with EGit:

Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page.

- Clone the JGit and EGit repositories and select Gerrit Configuration... in the context menu of the remote "origin" in the Git Repositories view to configure pushing to the code review queue.
- Alternative approach: Add a new review remote in the Git Repositories view and select Gerrit Configuration... in the context menu of the remote
  - From the appropriate Remotes node, create a New Remote and choose to Configure for Push. A unique name should be chosen, review is suggested.
  - Changes committed to your local clone can now be pushed to Gerrit using the review Remote. You will be prompted for your private key's passphrase if Eclipse is looking for it in the right place.
- Instead of using the Gerrit Configuration... wizard you can do the configuration steps manually:
  - Change the main URI or Add a Push URI (your Gerrit user name must be used here)
    - `ssh://username@eclipse.gerrithub.io:29418/(project).git`
  - In the Ref mapping section, add a RefSpec specification of `HEAD:refs/for/master`

- Visit our Gerrit Code Review instance to start reviewing

## Granularity of Changes

- Make small commits, as small as reasonable. This makes them easy to review.
- Each commit should have a commit message that explains very clearly what the commit sets out to achieve (unless this is abundantly clear from the code itself, which is basically only the case for trivial patches). Also, when you fix a bug then report which bug you fix. When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
- Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. The purpose of the commit is clear and can be understood easily by the reviewers and yourself.
- Do not break the build and tests for any commit: this is very important for bug hunting.
- Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
- A series of commits should work towards a 'feature' in a clear way and only 'enable' the feature in the last commit of the series.
- In a series of commits first lay the groundwork and then build on that towards the feature.

### Branches

When working with Gerrit, you can create local branches as you wish. When you are ready to push your changes, only the commits from your branch are pushed and are converted to reviews on Gerrit. The branch name itself is not visible on Gerrit.

Do not mix unrelated changes in branches: When you encounter a bug while working on something then create a new branch to fix the bug. Make sure you base it on the state of the remote branch that you want your fix to go to, e.g. origin/master. If you have other changes that depend on the bug being fixed then rebase your work on that new branch.

Merge/Rebase: If you want your branch to include new commits from the remote repository, rebase your local branch. The reason for this is that in Gerrit, changes are reviewed one commit at a time, and modified until all review feedback has been addressed. This is different from a pull request workflow, where the combined changes are reviewed and feedback is addressed with additional commits.

## Coding standards

Eclipse has standards for how to write code.

Coding conventions

Use interface guidelines

These documents have links to other document. Browse through them without expecting to learn everything, just so you know roughly what areas and types of details they covert. When you are not sure about how to write a piece of code or design the user interface, these are the two first places to look at.

In addition there is all the worlds collective knowledge on how to write programs that shine. When there is a conflict, the Eclipse guide lines and conventions take precedence.

Breaking the rules is ok if there is a very good reason and you can tell us what that reason is.

In addition to these general rules, we regard performance high. If the EGit plugin is slow in any way, that is a bug and should be reported and fixed. Java isn't slow, but there is a lot of slow Java code.

### Braces for one-line statements

Before 3.7.0 both in JGit and EGit, the preferred coding style was to leave off braces around statements with one line (with some exceptions to this rule), e.g.:

    if (condition)
        doSomething();

Starting with 3.7.0 braces are mandatory independently on the number of lines, without exceptions. The old code will remain as is, but the new changes should use the style below:

    if (condition) {
        doSomething();
    }

The main reason to the change was to simplify the review process, coding guidelines and to make them more consistent with Eclipse code formatter, see .

### Removing trailing whitespace

In JGit and EGit we have enabled the save action "Remove trailing white spaces on all lines" for Java sources. This works except for empty comment lines, see .

As a workaround, use the following sequence of commands in the Java editor to trick the save action:

- remove the offending trailing whitespace
- the save action re-adds the trailing whitespace
- CTRL-Z (CMD-Z on Mac) removes the re-added whitespace without triggering the save action again

Another workaround is to use this little script from the command line to edit away trailing whitespace from changed lines.

### Use of the "final" modifier

New code uses the "final" modifier in the following circumstances https://gerrit-review.googlesource.com/c/gerrit/+/61701/.

Always:

- final fields: marking fields as final forces them to be initialized in the constructor or at declaration
- final static fields: clearly communicates the intent
- where necessary to use final variables in inner anonymous classes
- for simple local constants, e.g. final int MAX_RETRIES = 5;

Optional:

- final classes: use when appropriate, e.g. API restriction
- final methods: similar to final classes

Never:

- local variables: it clutters the code, and makes the code less readable. When copying old code to new location, finals should be removed
- method parameters: similar to local variables

## Commit message guidelines

- The commit message header should fit on one line, try to keep it shorter than 50 characters, at most 72. A blank line separates it from the body of the message.
- The first line should be a clear and concise description about the change. It is recommended to start with the modified subsystem, followed by a colon and a description starting with capital letter and without period at the end. For example: `UploadPack: Use reachability checker to validate non-advertised wants`
- In case of release engineering tasks without bugzilla entries the commit message header may look like "[findbugs] Fix warning XYZ for String constructor". The prefix in brackets is an indication why this comes without a corresponding bug.
- Enter a newline before providing a more detailed description about the change.
- Format the commit message to have newline characters after every 60-70 characters.
- Find more reasoning about commit message formatting in "A Note About Git Commit Messages"
- Commit message trailers (everything following the last blank line in the commit message) in Key: value format are used for additional commit meta data. Some tools especially Gerrit parse this meta data to provide additional functionality. You can use the git interpret-trailers command to add or parse trailer lines at the end of commit messages.
  - If there is an associated bug number in Bugzilla about it, it should come as a Bug: trailer right before Gerrit's Change-Id trailer (if available) or towards the end. Use exactly the capitalization "Bug", since the automatic linking mechanism to the bug database is case sensitive.
  - A Gerrit Change-Id trailer is required for all changes pushed to Gerrit (to enable pushing new patchsets for the same change), it should be added in the format shown below. Use the Gerrit commit message hook or EGit to add the Change-Id.
  - A "Signed-off-by" can be added at the end of the commit message (see example below). It may be used to list all who modified (amended, rebased, cherry-picked) this change. This trailer isn't mandatory anymore since March 2021.

    CommitDialog: Fix the commit dialog to respect the workbench's selection

    Originally, the commit dialog would automatically check off all
    files in the dialog. This behaviour contradicts a user's expectation
    because their selection in the workbench is completely ignored. The
    code has been corrected to only preselect what the user has actually
    selected.

    Bug: 12345
    Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a
    Signed-off-by: Your Name <your.email@example.org>

## License Header

All new code files, including test code, must have a license header.

JGit is licensed under the Eclipse Distribution License which is a form of the New BSD License. Use of this license by an Eclipse project requires unanimous approval by the Board of Directors of the Eclipse Foundation which was approved in a meeting of the board in Sep 2009.

The license and copyright header to be used for JGit is

    /*
     * Copyright © YEAR CONTRIBUTOR[ and others]
     *
     * This program and the accompanying materials are made available under the
     * terms of the Eclipse Distribution License v. 1.0 which is available at
     * https://www.eclipse.org/org/documents/edl-v10.php.
     *
     * SPDX-License-Identifier: BSD-3-Clause
     */

EGit is licensed under the Eclipse Public License 2.0 and uses the license header

    /*******************************************************************************
     * Copyright © YEAR CONTRIBUTOR[ and others.]
     *
     * All rights reserved. This program and the accompanying materials
     * are made available under the terms of the Eclipse Public License 2.0
     * which accompanies this distribution, and is available at
     * https://www.eclipse.org/legal/epl-2.0/
     *
     * SPDX-License-Identifier: EPL-2.0
     *******************************************************************************/

The license header is placed at the very beginning of a file; in Java files above the "package" line.

See https://www.eclipse.org/legal/copyrightandlicensenotice.php for more information.

## Copyright

When contributing patches, you have to update the copyright section at the beginning of the file if there is one. Please follow the style that is already present in the file. Some examples follow.

When there is only one copyright present (from a person or a company), like this:

    Copyright (C) 2010, 2011 Some Name <some@example.org>

Change it like this (notice the updated year):

    Copyright (C) 2010, YEAR Some Name <some@example.org> and others.

If there is a section `Contributors:` below the legal text and your change is more than a few lines, you can add your name there and optionally describe the change and link to a bug number. You can also start such a section if you contributed a significant change.

When there are multiple copyright entries there, add yours as a separate line. So, given this:

    Copyright (C) 2010 Some Name <some@example.org>
    Copyright (C) 2011 Other Name <other@example.org>

Add another line:

    Copyright (C) 2010 Some Name <some@example.org>
    Copyright (C) 2011 Other Name <other@example.org>
    Copyright (C) YEAR Your Name <you@example.org>

For new files, copy one of the existing headers and start the copyright section with your name.

## Test before submitting

See the Manual alpha testing section for some advice about how to test you work yourself.

- Add automated tests for enhancements and bug fixes to ensure functional correctness and avoid regressions
- Run all existing tests. It does not take very long.
- Pay attention to the Java and Eclipse SDK baselines. EGit requires only Java 8 and Eclipse 4.4. You cannot use API's that are newer.

## Sending patches by mail

EGit and JGit can accept patches only via Gerrit as per Contributing_Patches.