| Contributing Patches | ||
|---|---|---|
|
|
|
|
| Website | Gerrit Code Review Cheatsheet | |
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.
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.
If you are an EGit/JGit committer or Eclipse Foundation administrator
All users need to click "Authorize gerritforge-ltd" which want to
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:
3. If you want to change your access scope
4. Click "login" to authenticate.
Git over SSH
When accessing GerritHub over SSH from git or EGit
ssh://username@eclipse.gerrithub.io:29418/eclipse-egit/egit
Git over HTTPS
When accessing GerritHub over HTTPS from git or EGit
https://<username>@eclipse.gerrithub.io/a/eclipse-egit/egitssh-keygen -t ed25519 -C "your_email@youremail.com"
ssh -p 29418 username@eclipse.gerrithub.io
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:
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:
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).
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
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
Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page.
ssh://username@eclipse.gerrithub.io:29418/(project).git HEAD:refs/for/masterWhen 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.
Eclipse has standards for how to write code.
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.
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 .
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:
Another workaround is to use this little script from the command line to edit away trailing whitespace from changed lines.
New code uses the "final" modifier in the following circumstances https://gerrit-review.googlesource.com/c/gerrit/+/61701/.
Always:
Optional:
Never:
UploadPack: Use reachability checker to validate non-advertised wantsCommitDialog: 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>
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.
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.
See the Manual alpha testing section for some advice about how to test you work yourself.
EGit and JGit can accept patches only via Gerrit as per Contributing_Patches.
|
|
|
|
| Website | Gerrit Code Review Cheatsheet |