Skip to main content
Jump to: navigation, search

Difference between revisions of "EGit/Contributor Guide"

m (Manual Import)
(Use of the "final" modifier)
 
(443 intermediate revisions by 33 users not shown)
Line 1: Line 1:
{{:DocumentationGuidelines/DraftHeader}} {{EGit}}
+
= Communication =
  
= Development IDE Configuration =
+
{| cellpadding="3" cellspacing="0" border="1"
 +
!Channel
 +
!JGit
 +
!EGit
 +
|-
 +
|Developer Mailing List
 +
|[https://dev.eclipse.org/mailman/listinfo/jgit-dev JGit developer mailing list]
 +
|[https://dev.eclipse.org/mailman/listinfo/egit-dev EGit developer mailing list]
 +
|-
 +
|Build Notices Mailing List
 +
|[https://dev.eclipse.org/mailman/listinfo/jgit-build JGit build notices mailing list]
 +
|[https://dev.eclipse.org/mailman/listinfo/egit-build EGit build notices mailing list]
 +
|-
 +
|Reporting Bugs
 +
|[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JGit&rep_platform=All&op_sys=All File new JGit bug]
 +
|[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit&rep_platform=All&op_sys=All File new EGit bug]
 +
|-
 +
|User Forum
 +
|colspan=2|[https://www.eclipse.org/forums/index.php?t=thread&frm_id=48 EGit User Forum]
 +
|}
  
EGit and JGit have Java 5.0 and Eclipse Platform 3.5 as minimum requirements, so dependencies to newer Java and platform versions must be avoided.
+
<br/>
  
In order to minimize the inadvertent introduction of dependencies to Java 6.0, add both a Java5 and a Java 6 SDK to your  workspace. Do this in Window/Preferences -> Java/Installed JREs. Then configure your Execution Environments so that J2SE-1.5 refer to a Java 5 SDK and JavaSE-1.6 refer to a Java 6 installation.
+
= Automated Developer Setup =
 +
The fastest developer setup for contributing to JGit/EGit is to use the Eclipse Installer and the
 +
EGit project setup to prepare an Eclipse IDE for JGit/EGit:
 +
* download and unpack the [https://www.eclipse.org/downloads/eclipse-packages/ Eclipse Installer]
 +
* start the Eclipse Installer
 +
* select the advanced mode
 +
[[File:Oomph-01-advanced-mode.png]]
 +
* if the right most icon in the bottom toolbar of the installer rotates, there is an update available for the installer, which should be installed before continuing
 +
* if you are behind a proxy, change the proxy settings from the toolbar at the bottom
 +
[[File:Oomph -01a-proxy-settings.png]]
 +
* on the product page select "Eclipse IDE for Eclipse Committers" and click "Next"
 +
[[File:Oomph-02-proxy-product-selection.png]]
 +
* on the project page select project "EGit" and click "Next"
 +
[[File:Oomph-03-project-egit.png]]
 +
* on Variables page accept default target platform, to fine tune variables click "Show all variables", click "Next"
 +
* on the Confirmation page click "Finish"
 +
[[File:Oomph-04-installer-progress.png]]
 +
* the installer installs the chosen IDE and starts it, as soon as the installer says "Press Finish to close the dialog" you can close the installer window
 +
* the newly installed IDE will automatically clone the JGit and EGit repositories and configure the workbench for JGit/EGit development. You can observe the setup progress in the toolbar, if necessary you can reopen the setup wizard by clicking its icon in the status bar
 +
[[File:Oomph-05-eclipse-progress.png]]
 +
* when the setup finished the IDE should looks similar to this
 +
[[File:Oomph-06-ide.png]]
  
To be completely on the safe side for reducing the risk of breaking Platform 3.5 compatibility, you would have to have a 3.5 IDE ready on which to check your code. In general, the effort for this is probably not justified, unless you are introducing major UI functionality. Just keep the minimum requirements in mind when using Platform API. Eclipse API's are usually marked with a @since tag.
+
If you want to improve the EGit project setup, check the setup file in tools\oomph\EGit.setup (in your newly cloned egit repository). You can find more information about Oomph at
 +
* https://help.eclipse.org/
 +
* https://projects.eclipse.org/projects/tools.oomph
 +
* https://wiki.eclipse.org/Eclipse_Installer
 +
* https://wiki.eclipse.org/Eclipse_Oomph_Authoring
  
= Obtaining Sources =
+
= Manual Developer Setup =
 +
== Obtaining Sources ==
 +
EGit and JGit are self hosted in Git. You can browse the repositories on the web:
 +
[https://git.eclipse.org/c/egit/ EGit], [https://git.eclipse.org/c/jgit/ JGit]
  
EGit and JGit are self hosted in Git. Browse the repositories in [http://egit.eclipse.org/w/ gitweb].
+
The first section below describes how to clone a repository and can be skipped if you have done this before.
<p>There are several ways to obtain a copy of each repository:</p>
+
The next section lists the repositories and their URLs.
  
== From the command line ==
+
=== Cloning ===
<pre style="width: 40em;">git clone git://egit.eclipse.org/jgit.git jgit
+
==== On the command line ====
git clone git://egit.eclipse.org/egit.git egit
+
</pre>
+
  
== From an installed EGit plugin ==
+
<pre style="width: 40em;">
 +
git clone <enter URL>
 +
</pre>
  
*File &gt; Import &gt; Git > Git Repository
+
After that, import the projects into Eclipse using Import > Existing Projects into Workspace.
*Enter URI:
+
<pre style="width: 40em;">git://egit.eclipse.org/jgit.git</pre>
+
*Import projects
+
  
*File &gt; Import &gt; Git > Git Repository
+
==== Using EGit (see [https://www.eclipse.org/egit/download/ download page]) ====
*Enter URI:
+
<pre style="width: 40em;">git://egit.eclipse.org/egit.git</pre>
+
*Import projects
+
  
To compile you also need [[#Libraries from Orbit|libraries from Orbit]].
+
First, verify that the default repository folder as set on the main Git preference page is to your liking.
 +
 
 +
Then, clone the repository and import the projects:
 +
 
 +
* Open ''File'' &gt; ''Import...'' and select ''Git'' > ''Projects from Git''
 +
* Selet ''URI''
 +
* Enter the URL (see next section)
 +
* Import existing projects into the workspace from the newly created working directory
 +
 
 +
=== Repositories ===
 +
 
 +
To develop EGit, the EGit and JGit repositories are needed, the others are optional. To develop JGit, only JGit is needed.
 +
 
 +
==== EGit ====
 +
 
 +
URL: https://git.eclipse.org/r/egit/egit.git
 +
 
 +
This is the main repository, where the standard EGit feature is developed. It contains the code for the UI and Eclipse integration.
 +
 
 +
==== JGit ====
 +
 
 +
URL: https://git.eclipse.org/r/jgit/jgit.git
 +
 
 +
This is the Java implementation of Git used by EGit, for working with Git repositories.
 +
 
 +
==== EGit GitHub Integration ====
 +
 
 +
URL: https://git.eclipse.org/r/egit/egit-github.git
 +
 
 +
EGit also provides tools for integrating with GitHub and Mylyn tasks.
 +
 
 +
For getting the dependencies, open the file <code>org.eclipse.mylyn.github-feature/github.target</code> ([https://git.eclipse.org/c/egit/egit-github.git/plain/org.eclipse.mylyn.github-feature/github.target view on web]) and select ''Set as Target Platfrom''.
 +
 
 +
==== EGit PDE Tools ====
 +
 
 +
URL: https://git.eclipse.org/r/egit/egit-pde.git
 +
 
 +
EGit also provides tools for integrating with [[PDE/Build|PDE Build]] and Eclipse RelEng Tools. If you are an Eclipse developer using PDE Build and/or the Eclipse RelEng tools you might be interesting in the following as well. Otherwise you might just skip this section.
 +
 
 +
In addition to the [[#Dependencies|dependencies]] required for JGit and EGit you also need Eclipse PDE (>= 3.6.1) as well as <code>org.eclipse.releng.tools</code> in your target platform or checked out from Git in your workspaces.
 +
 
 +
== Development IDE Configuration ==
 +
 
 +
Download and install the Eclipse package "Eclipse IDE for Eclipse Committers" or "Eclipse for RCP and RAP Developers" from here, if you don't already have it:
 +
 
 +
https://www.eclipse.org/downloads/packages/
 +
 
 +
=== Tools ===
 +
 
 +
To install all the necessary tools to work on EGit/JGit, there is a [https://git.eclipse.org/c/egit/egit.git/plain/tools/egit-developer-tools.p2f egit-developer-tools.p2f] file which you can use as follows:
 +
 
 +
* File > Import > Install > Install Software Items from File
 +
* Browse...
 +
** Go to the location of your egit repository, open the ''tools'' directory and select ''egit-developer-tools.p2f''
 +
** Alternatively, if you only want to contribute to JGit, download the file from the above link and select it
 +
* All the items you don't already have should be selected automatically
 +
* Finish the wizard
 +
* Restart
 +
 
 +
=== Java Requirements ===
 +
 
 +
EGit and JGit have Java 8.0 and [https://wiki.eclipse.org/EGit/FAQ#What_versions_of_Eclipse_does_EGit_target.3F Eclipse Platform 4.6 (Neon)] as minimum requirements, so dependencies to newer Java and platform versions must be avoided.
 +
 
 +
We are using ''API Tools Environment Descriptions'' (see changes for [https://git.eclipse.org/r/#/c/4785/ JGit] and [https://git.eclipse.org/r/#/c/4365/ EGit]) to facilitate detecting code which isn't working on Java 8. If you followed the instructions in the ''Tools'' section above, the necessary descriptions should already be installed. Otherwise install ''API Tools Environment Descriptions'' from the release train repository, see [[Execution_Environments#Installing_Execution_Environment_Descriptions|Installing Execution Environment Descriptions]].
 +
 
 +
=== Dependencies ===
 +
 
 +
After importing the EGit and JGit projects in Eclipse, they will not compile due to missing dependencies.
 +
Set a Target Platform to fix this
 +
 
 +
[[Image:EGit-Target-Platforms.png‎|right|EGit target platforms in org.eclipse.egit.target]]
 +
* Open the ''org.eclipse.egit.target'' project
 +
* Choose the ''egit-<version>.target'' file matching the version of your Eclipse platform (e.g. 4.5 for Mars) and open it (this may take a while as it downloads the indexes of the p2 repositories the target platform refers to)
 +
* In the resulting editor, click on the ''Set as Target Platform'' link at the top right (this may also take a while since it downloads the dependencies)
 +
 
 +
After that, the workspace should build cleanly. If not, try Project > Clean... > All. If this also doesn't help open Preferences > Plug-In Development > Target Platform,
 +
select the checked target platform and click "Reload..." this will flush PDE's bundle cache and re-download the artifacts listed in the target platform.
 +
 
 +
There are different target definitions, one for each version of Eclipse that EGit supports. The one you select will be the one that is started if you want to try out a feature or bug fix.
 +
 
 +
You can always switch between them to test on different Eclipse versions. E.g. when you are developing some major UI functionality, you should try it with the oldest supported Eclipse release to make sure it doesn't depend on API that is only available in later versions.
 +
 
 +
= Running EGit from Eclipse =
 +
 
 +
Now that everything builds, the next step is to run an Eclipse instance with the EGit/JGit code of the workspace:
 +
 
 +
* Right click on the ''org.eclipse.egit.ui'' project
 +
* Debug As &gt; Eclipse Application
 +
 
 +
This should create a new launch configuration and start a new nested Eclipse instance in debug mode. The created launch configuration can be edited, e.g. to change where the workspace of the nested Eclipse should be located.
 +
 
 +
The launch configuration can also be used in normal (non-debug) mode of course.
 +
 
 +
Also see the [https://help.eclipse.org/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Flaunchers%2Feclipse_application_launcher.htm reference on eclipse application launchers].
 +
 
 +
<br/>
  
 
= Builds =
 
= Builds =
  
EGit and JGit builds run on build.eclipse.org via Hudson using
+
The central EGit and JGit builds run on the Jenkins build infrastructure provided by the Eclipse foundation.
* [http://maven.apache.org/download.html Maven 3.0-beta-1]
+
* [https://ci.eclipse.org/egit/ EGit Jenkins instance]
* [http://docs.codehaus.org/display/M2ECLIPSE/Tycho+user+docs Tycho Maven plugin]
+
* [https://ci.eclipse.org/jgit/ JGit Jenkins instance]
  
Hudson
+
Prerequisites for the Maven build are
* [https://build.eclipse.org/hudson/job/jgit JGit@build.eclipse.org]
+
* Java 8, updating JGit to Java 11 is [https://bugs.eclipse.org/bugs/show_bug.cgi?id=569917 planned for 6.0]
* [https://build.eclipse.org/hudson/job/egit EGit@build.eclipse.org]
+
* [https://maven.apache.org/download.html at least Maven 3.5.2]
 +
* see [https://maven.apache.org/settings.html settings.xml reference] on how to do basic Maven configuration
 +
* if you want to learn how Maven works start reading [https://maven.apache.org/guides/getting-started/index.html the Maven Getting Started Guide]
  
 
== JGit ==
 
== JGit ==
* JGit can be built using Maven 2 or 3.
+
* JGit can be built using Maven or Bazel
* JGit packaging project (Eclipse feature and update site) are built using Maven 3 and Tycho.
+
* use Java 8 to run the JGit build
 +
* JGit packaging projects (Eclipse features and p2 repository) are built using Maven and Tycho.
  
 
== EGit ==
 
== EGit ==
* EGit is built using Maven 3 and Tycho.
+
* EGit is built using Maven and Tycho.
  
 
== Mailing Lists ==
 
== Mailing Lists ==
Line 57: Line 196:
 
*[https://dev.eclipse.org/mailman/listinfo/egit-build Subscribe to egit-build@eclipse.org]
 
*[https://dev.eclipse.org/mailman/listinfo/egit-build Subscribe to egit-build@eclipse.org]
  
== Maven Build Sequence ==
+
== Maven Build ==
* Due to a [https://docs.sonatype.org/display/TYCHO/Dependency+on+pom-first+artifacts current limitation of Tycho 0.8.0] it is not possible to mix pom-first and manifest-first builds in the same reactor build hence the pom-first JGit build has to run separately before the build for the manifest-first JGit packaging project.
+
 
* The 3 builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
+
To build JGit or EGit versions <= 5.12.0 maven must be run using Java 1.8. Ensure that environment variable <tt>JAVA_HOME</tt> points to a Java 1.8 installation.
* To run the build behind a firewall follow http://maven.apache.org/guides/mini/guide-proxies.html and for Tycho additionally pass proxy settings via system properties (https://issues.sonatype.org/browse/TYCHO-279): <tt>mvn <b>-DproxyHost=myproxy -DproxyPort=1080</b> ...</tt>
+
 
 +
EGit versions >= 5.12.1 can be built with any Java >= 1.8, but the build uses [https://maven.apache.org/guides/mini/guide-using-toolchains.html maven toolchain] definitions. To run a local EGit build for these versions (including the 'master' branch, i.e. EGit nightly), you need to have a local file <tt>'''~/.m2/toolchains.xml'''</tt> providing at least a JDK toolchain definition for "JavaSE-1.8":
 +
<pre style="width: 55em;">
 +
<?xml version="1.0" encoding="UTF8"?>
 +
<toolchains>
 +
  <toolchain>
 +
      <type>jdk</type>
 +
      <provides>
 +
        <id>JavaSE-1.8</id>
 +
        <version>1.8</version>
 +
      </provides>
 +
      <configuration>
 +
        <jdkHome>/absolute/path/to/jdk1.8</jdkHome>
 +
      </configuration>
 +
  </toolchain>
 +
  <toolchain>
 +
      <type>jdk</type>
 +
      <provides>
 +
        <id>JavaSE-11</id>
 +
        <version>11</version>
 +
      </provides>
 +
      <configuration>
 +
        <jdkHome>/absolute/path/to/jdk11</jdkHome>
 +
      </configuration>
 +
  </toolchain>
 +
</toolchains>
 +
</pre>
 +
The <tt>jdkHome</tt> directory is the one that contains the <tt>bin</tt> directory in which there is the <tt>java</tt> executable.
 +
 
 +
If you can, include already a definition for a Java 11 toolchain as shown above. EGit and JGit may require a minimum of Java 11 in the not-too-distant future.
 +
 
 +
Building JGit with maven currently requires running maven with Java 1.8 in all cases.
 +
 
 +
* Due to a [https://wiki.eclipse.org/Tycho/How_Tos/Dependency_on_pom-first_artifacts limitation of Tycho] it is not possible to mix pom-first and manifest-first builds in the same reactor build hence the pom-first JGit build has to run separately before the build for the manifest-first JGit packaging project.
 +
* The local maven builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
 +
* To run the build behind a firewall follow https://maven.apache.org/guides/mini/guide-proxies.html  
  
 
Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):
 
Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):
<pre style="width: 55em;">[~/src/jgit] $ mvn clean install
+
<pre style="width: 55em;">
 +
[~/src/jgit] $ mvn clean install
 
[INFO] Scanning for projects...
 
[INFO] Scanning for projects...
 
...
 
...
Line 74: Line 249:
  
 
[~/src/egit] $ mvn clean install
 
[~/src/egit] $ mvn clean install
 +
[INFO] Scanning for projects...
 +
...
 +
 +
[~/src/jgit] $ cd ../egit-github
 +
 +
[~/src/egit-github] $ mvn clean install
 
[INFO] Scanning for projects...
 
[INFO] Scanning for projects...
 
...
 
...
Line 82: Line 263:
 
to the jgit p2 repository has to be injected via system property:
 
to the jgit p2 repository has to be injected via system property:
  
<pre style="width: 55em;">[~/src/egit] $ mvn clean install -Djgit-site=file:/path/to/
+
[~/src/egit] $ mvn clean install -Djgit-site=file:/path/to/jgit/org.eclipse.jgit.packaging/org.eclipse.jgit.repository/target/repository
                          org.eclipse.jgit.updatesite/target/site
+
 
</pre>
+
in the same way you can configure a custom path for the build of egit-github to the egit p2 repository
 +
 
 +
[~/src/egit-github] $ mvn clean install -Degit-site=file:/path/to/egit/org.eclipse.egit.repository/target/repository
 +
 
 +
The Jenkins build uses (for SNAPSHOT builds):
 +
[~/src/egit] $ mvn clean install -Djgit-site=https://repo.eclipse.org/content/unzip/snapshots.unzip/
 +
                      org/eclipse/jgit/org.eclipse.jgit.repository/${JGIT_VERSION}/org.eclipse.jgit.repository-${JGIT_VERSION}.zip-unzip/
 +
 
 +
If you wan to build EGit for a specific Eclipse platform use the corresponding EGit target platform. For instance, to build for Eclipse 4.19 (2021-03), use the <code>egit-4.19</code> target platform:
 +
[~/src/egit] $ mvn -Dtarget-platform=egit-4.19 clean install
 +
 +
See the contents of bundle <code>org.eclipse.egit.target</code> for the available target platforms.
 +
 
 +
Upon a successful build, a p2 update site should be generated inside ''egit/org.eclipse.egit.repository/target/repository''. If not, make sure the target platform has been downloaded from within Eclipse (Windows>Preferences>Plug-in Development>Target Platform). The default target platform defined in the maven build is currently Eclipse 4.6 (Neon). If you skip setting the system property <code>target-platform</code> the target platform for Eclipse 4.6 will be used. EGit built with that target platform can run on any Eclipse >= 4.6. If you choose a higher target platform, the EGit produced may not run on Eclipses older than the target platform version.
 +
 
 +
==Dependencies and License Check==
 +
 
 +
In order to update the list of dependencies run the dash-licenses Maven plugin
  
The hudson build on build.eclipse.org uses:
+
<pre style="width: 55em;">
<pre style="width: 55em;">[~/src/egit] $ mvn clean install -Djgit-site=https://build.eclipse.org/hudson/job/
+
mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIES
                          jgit/lastSuccessfulBuild/artifact/org.eclipse.jgit.packaging/
+
                          org.eclipse.jgit.updatesite/target/site/
+
 
</pre>
 
</pre>
  
== Signing ==
+
then sort the entries in the file <code>DEPENDENCIES</code> and check for changes against the previous version.
 +
If necessary file CQs for new dependencies which are flagged ''restricted'' by the tool.
 +
See the [https://www.eclipse.org/projects/handbook/#ip-license-tool Eclipse projects handbook].
  
To sign the EGit build, you need to have ssh access to build.eclipse.org and the ability to run '''/usr/bin/sign'''
+
Currently this tool requires Java 11, hence first build JGit/EGit using the Java version they require
 +
and then use Java 11 to run the license check.
  
At the moment, Chris Aniszczyk (caniszczyk) and Matthias Sohn (msohn) have signing privileges.
+
==JGit Bazel Build==
 +
Since Gerrit is built using [https://www.bazel.io/ Bazel] a Bazel build was also implemented for JGit.
 +
This simplifies working on Gerrit features which also require changes in JGit.
 +
* [https://www.bazel.io/versions/master/docs/install.html Install Bazel]
 +
* To build all libraries run
 +
bazel build :all
 +
* The following test labels are supported: api, attributes, dfs, diff, http, lfs, lfs-server, nls, notes, pack, patch, pgm, reftree, revplot, revwalk, storage, submodule, symlinks, transport, treewalk, util
 +
* To run all tests execute
 +
bazel test //...
 +
* To run specific tests, using labels:
 +
bazel test --test_tag_filters=api,dfs,revplot,treewalk //...
 +
* to rerun all tests ignoring cached test results execute
 +
bazel test //... --cache_test_results=NO
 +
* to set number of concurrent test runs
 +
bazel test //... --jobs=4
 +
* to debug a test run
 +
bazel test --test_output=streamed --test_filter=<fully qualified test method> <test target>
 +
e.g.
 +
bazel test --test_output=streamed --test_filter=org.eclipse.jgit.api.GitConstructionTest.testClose //org.eclipse.jgit.test:org_eclipse_jgit_api_GitConstructionTest
 +
* to configure loggers for test runs edit org.eclipse.jgit.test/tst-rsrc/simplelogger.properties, see the [https://www.slf4j.org/api/org/slf4j/impl/SimpleLogger.html slf4j SimpleLogger documentation]
 +
* to run tests repeatedly use
 +
bazel test --runs_per_test=3 <test target>
 +
* since 5.4.0 builds run with [https://github.com/google/error-prone the errorprone static analyzer] by default. If you want to enable it for older JGit versions execute
 +
bazel build --java_toolchain //tools:error_prone_warnings_toolchain :all
  
The first step is to ensure you're in a place you can sign on build.eclipse.org
 
  
cd /home/data/httpd/download-staging.priv/commonBuild
+
Note that the Bazel build does not yet support building JGit OSGi bundles, Eclipse features and the p2 repository which are required to install JGit in Eclipse.
  
Next you run the signing command (Usage: /usr/bin/sign <file> <mail|nomail> [outputDir]) on a zip of the EGit repo...
+
== FindBugs and PMD ==
  
sign egit-p2-repo.zip my@email.com /home/data/users/caniszczyk/egit-0.8
+
As part of the build, JGit and EGit run FindBugs and PMD to find issues.
 +
* [https://ci.eclipse.org/jgit/job/jgit/findbugs JGit FindBugs Results]
 +
* [https://ci.eclipse.org/jgit/job/jgit/dry JGit DRY (PMD) Results]
 +
* [https://ci.eclipse.org/egit/job/egit/findbugs EGit FindBugs Results]
 +
* [https://ci.eclipse.org/egit/job/egit/dry EGit DRY (PMD) Results]
  
After that, you can publish the zip that is generated with the signing information.
+
== Checking for JGit API Changes using API Baseline ==
 +
 
 +
The JGit projects have API tooling enabled. In order to use PDE API tools to get assistance with maintaining API changes and additions you need to set an API baseline:
 +
* download the p2 repository for the latest EGit release (which includes the JGit artifacts) to a local folder, e.g. <code>~/egit-releases/updates-4.9.1</code>, find the p2 repository URLs [https://wiki.eclipse.org/EGit/FAQ#Where_can_I_find_older_releases_of_EGit.3F here] and download the p2 repository of the latest minor release (service releases don't change API) using the corresponding link in the last column of that table
 +
* in Eclipse click "Preferences > Plug-In Development > API Baselines", click "Add Baseline..." and define a new baseline (e.g. egit-4.9.1) and point it to the local copy of the corresponding EGit p2 repository.
 +
* the API tools will then raise warning/errors for all detected problems and provide quick fixes helping to resolve these problems
 +
* see the [https://wiki.eclipse.org/PDE/API_Tools/User_Guide PDE API Tools User Guide] for more details.
 +
 
 +
== Signing and Publishing ==
 +
EGit and JGit builds running on the JGit/EGit Jenkins instances are automatically signed
 +
(using the [[Common_Build_Infrastructure#Signing_tool | CBI eclipse-jarsigner-plugin]]) and published to the folder
 +
<pre>
 +
master branch:        /home/data/httpd/download.eclipse.org/egit/updates-nightly
 +
latest stable branch:  /home/data/httpd/download.eclipse.org/egit/updates-stable-nightly
 +
</pre>
 +
 
 +
* To enable signing the maven profile <code>eclipse-sign</code> must be enabled via the option <code>-P eclipse-sign</code> in the respective build jobs running at https://ci.eclipse.org/egit/
 +
 
 +
== Contribution to Release Train ==
 +
 
 +
The release train contribution for JGit and EGit is maintained in the git repository
 +
<pre>ssh://git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git</pre>
 +
in the file
 +
<pre>egit.aggrcon</pre>
 +
 
 +
The release train build is coordinated on the [https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev cross-project-issues-dev mailing list]
 +
 
 +
<br/>
  
 
= Documentation =
 
= Documentation =
 +
== JGit ==
 +
The JGit project generates a project report and javadocs using a Maven site. This Maven site is deployed to https://download.eclipse.org/jgit/site/${project.version}.
 +
E.g. https://download.eclipse.org/jgit/site/4.4.1.201607150455-r/
  
The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using [http://wiki.eclipse.org/Mylyn/WikiText Mylyn WikiText] to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the [http://wiki.eclipse.org/EGit/User_Guide EGit User's Guide]. Have a look at the [[DocumentationGuidelines/StyleGuidelines|Style Guidelines]] and [[Eclipse_Doc_Style_Guide|Eclipse Documentation Style Guide]] to get some guidance on how to write good documentation. More on that can be found [[DocumentationGuidelines|here]].
+
Generating the site:
 +
'''$ mvn site:site'''
  
The documentation is contained in the '''org.eclipse.egit.doc''' plug-in. The '''build-helper.xml''' drives the generation of the help content. It is integrated into the maven build. The regular maven build of '''org.eclipse.egit.doc'''
+
Staging the site locally under ./target/staging:
 +
'''$ mvn site:stage'''
 +
 
 +
If you can connect to build.eclipse.org over ssh (ask webmaster if you are a committer and need ssh access) you can deploy a local build of the site:
 +
'''$ mvn site:deploy'''
 +
The site is deployed under https://download.eclipse.org/jgit/site/${project.version}
 +
 
 +
To select the ssh key to use for deploying over ssh add the following section to your Maven settings.xml:
 +
<server>
 +
      <id>jgit.website</id>
 +
      <username>username</username>
 +
      <privateKey>${user.home}/.ssh/id_rsa</privateKey>
 +
      <password>{<encrypted passphrase>}</password>
 +
      <filePermissions>664</filePermission>
 +
      <directoryPermissions>775</directoryPermissions>
 +
      <configuration></configuration>
 +
</server>
 +
 
 +
Password encryption for Maven is described in https://maven.apache.org/guides/mini/guide-encryption.html
 +
 
 +
To deploy the site from JGit HIPP (Hudson) at https://hudson.eclipse.org/jgit/ enable the Maven profile '''build-server''' and add the Maven goals '''site:site site:deploy'''.
 +
 
 +
If you uploaded the site for a new release update the index
 +
/home/data/httpd/download.eclipse.org/jgit/docs/latest/apidocs/index.html
 +
to refer to the new release's site.
 +
 
 +
== EGit ==
 +
The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using [https://wiki.eclipse.org/Mylyn/WikiText Mylyn WikiText] to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the [https://wiki.eclipse.org/EGit/User_Guide EGit User's Guide]. Have a look at the [[DocumentationGuidelines/StyleGuidelines|Style Guidelines]] and [[Eclipse_Doc_Style_Guide|Eclipse Documentation Style Guide]] to get some guidance on how to write good documentation. More on that can be found [[DocumentationGuidelines|here]].
 +
 
 +
The documentation is contained in the '''org.eclipse.egit.doc''' plug-in. The '''build-help.xml''' drives the generation of the help content. It is integrated into the maven build. The regular maven build of '''org.eclipse.egit.doc'''
 
  '''$ mvn clean install'''  
 
  '''$ mvn clean install'''  
 
will only package the help content committed to the egit repository. To update the help content by downloading the latest documentation from the wiki run
 
will only package the help content committed to the egit repository. To update the help content by downloading the latest documentation from the wiki run
Line 119: Line 404:
  
 
The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.
 
The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.
 +
 +
<br/>
  
 
= Tests =
 
= Tests =
 
== JGit Unit Tests ==
 
== JGit Unit Tests ==
The JGit unit tests are executed during the maven build for the bundle ''org.eclipse.jgit.test''.
+
The JGit unit tests are executed during the maven build.
To run them from the Eclipse workbench use the launch configurations which are part of the sources of the bundle ''org.eclipse.jgit.test''.
+
To run them from the Eclipse workbench use the launch configurations which are part of the sources of the test bundles'.
  
 
== JGit HTTP Tests ==
 
== JGit HTTP Tests ==
The JGit HTTP tests rely on the Jetty web container. To run these tests from Eclipse download
+
The JGit HTTP tests in ''org.eclipse.jgit.http.test'' rely on the Jetty web container.
[http://download.eclipse.org/jetty/7.0.1.v20091125/dist/ Jetty 7.0.1.v20091125] and unzip it
+
 
in some folder. Then add its lib folder to your target platform :
+
To run these tests from Eclipse the Jetty feature is needed. Use one of the target platforms as described in [[#Dependencies|dependencies]].
* Preferences > Plug-in Development > Target Platform
+
 
* select "Running Platform (Active)"
+
Alternatively, install "Jetty 9.4.20.v20190813" from https://download.eclipse.org/jetty/updates/jetty-bundles-9.x/9.4.20.v20190813/
* Add the lib folder of the Jetty distribution
+
  
 
== EGit Core Tests ==
 
== EGit Core Tests ==
 
The EGit Core tests are executed during the maven build for the bundle ''org.eclipse.egit.core.test''.
 
The EGit Core tests are executed during the maven build for the bundle ''org.eclipse.egit.core.test''.
 +
 
To run them from the Eclipse workbench use the launch configuration which is part of the sources of the test bundle ''org.eclipse.egit.core.test''.
 
To run them from the Eclipse workbench use the launch configuration which is part of the sources of the test bundle ''org.eclipse.egit.core.test''.
  
 
== EGit UI Tests ==
 
== EGit UI Tests ==
The EGit UI tests are using SWTBot, to run them you need 'SWTBot for Eclipse Testing' feature.
+
The EGit UI tests are using SWTBot, using the 'SWTBot for Eclipse Testing' feature.
=== Manual ===
+
Install the SWTBot matching your Eclipse version
+
from http://www.eclipse.org/swtbot/downloads.php
+
  
=== Automatic ===
+
You need to install at least "SWTBot for Eclipse Testing" and "SWTBot IDE Feature":
Using [[RCP_FAQ#What_is_the_recommended_target_platform_setup.3F_Or:_How_can_I_build_and_run_my_RCP_app_against_a_different_version_of_the_Eclipse_base.3F|target platform]] definition file:
+
* https://download.eclipse.org/technology/swtbot/snapshots/
* http://egit.eclipse.org/r/382 provides core Galileo-based dependencies and SWTBot for Eclipse Testing feature. You still need JGit projects to be opened in the workspace.
+
* http://egit.eclipse.org/r/383 extends the previous one with JGit from the nightly update site. This patch makes it possible to develop EGit plug-ins without checking out JGit projects.
+
  
How to use it:
+
Starting a UI test from Eclipse:
* pull either first or both patches
+
* select the test class or test method
* open Target Platform Preferences page (Window - Preferences - Plug-in development - Target Platform)
+
* click '''Run As > SWTBot Test'''
* activate 'SWTBot-based UI plug-in tests' target platform
+
 
 +
[[Image:Start-swtbot-test.png]]
 +
 
 +
Do not touch the mouse or keyboard when the UI test is running since this may
 +
disturb the UI test by e.g. moving the current focus to another window.
  
 
=== During Maven Build ===
 
=== During Maven Build ===
  
The tests are executed in the integration-test phase of the [http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html default Maven lifecycle].
+
The tests are executed in the integration-test phase of the [https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html default Maven lifecycle].
 +
 
 +
If you want to skip execution of UI tests (only execute core tests):
 +
 
 +
mvn -P skip-ui-tests clean install
 +
 
 +
If you want to skip all tests:
 +
 
 +
mvn clean install -Dmaven.test.skip=true
 +
 
 +
== Auxilary testing tools ==
 +
 
 +
Any code, including testing code, does not always do what you expected it to. The most common failure is probably the failure to actually execute the part of the code you wanted to test. Code coverage tools like [https://www.eclemma.org/ EclEmma] can easily visualize what part of the code is being executed.
 +
 
 +
= Bugs =
 +
 
 +
If you are looking for bugs/enhancements to start contributing, they have the keyword "helpwanted" or "bugday":
 +
 
 +
[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted%2C%20bugday%2C%20&keywords_type=anywords&list_id=7364111&resolution=---&query_format=advanced&product=EGit EGit bugs with helpwanted or bugday]
 +
 
 +
[https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted%2C%20bugday%2C%20&keywords_type=anywords&list_id=8951656&product=JGit&query_format=advanced&resolution=--- JGit bugs with helpwanted or bugday]
 +
 
 +
== Links ==
 +
=== Filing Bugs ===
 +
==== How to file bugs ====
 +
*[[FAQ_How_do_I_report_a_bug_in_Eclipse%3F | How do I report a bug in Eclipse?]]
 +
*[https://bugs.eclipse.org/bugs/page.cgi?id=bug-writing.html Bug Writing Guidelines]
 +
*[https://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively] by Simon Tatham
 +
 
 +
==== File a bug ====
 +
* [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit&rep_platform=All&op_sys=All File a bug for EGit]
 +
* [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JGit&rep_platform=All&op_sys=All File a bug for JGit]
 +
 
 +
==== File a bug for a vulnerability ====
 +
If you discovered a vulnerability you want to report
 +
* create a bug in Bugzilla here https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JGit
 +
* click "Show Advanced Fields"
 +
* and check the option "Committer-only group for handling security advisories in a closed fashion."
 +
* describe the vulnerability
 +
this will ensure that the discussion on the vulnerability is kept private between the reporter and the committer group
 +
until the project prepared a release fixing the vulnerability
 +
 
 +
=== Bug Reports and Links ===
 +
{| cellpadding="3" cellspacing="0" border="1"
 +
!Trends (bugs and enhancements)
 +
!EGit
 +
!JGit
 +
|-
 +
|Open by component (date range editable)
 +
|[https://bugs.eclipse.org/bugs/chart.cgi?category=EGit&datefrom=2011-01-01&dateto=&gt=1&label0=EGit%20Core%20Open&label1=EGit%20UI%20Open&labelgt=Grand%20Total&line0=1480&line1=1478&name=1478&subcategory=UI&action=wrap&width=1000&height=500 Open]
 +
|[https://bugs.eclipse.org/bugs/chart.cgi?category=JGit&datefrom=2011-01-01&dateto=&label0=JGit%20Open&line0=1592&name=1592&subcategory=JGit&action=wrap&width=1000&height=500 Open]
 +
|-
 +
|Open by status
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=EGit&datasets=NEW&datasets=REOPENED&datasets=UNCONFIRMED&datasets=ASSIGNED Open]
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=JGit&datasets=NEW&datasets=REOPENED&datasets=UNCONFIRMED&datasets=ASSIGNED Open]
 +
|-
 +
|Assigned
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=EGit&datasets=ASSIGNED Assigned]
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=JGit&datasets=ASSIGNED Assigned]
 +
|-
 +
|Open and closed by status
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=EGit&datasets=NEW&datasets=REOPENED&datasets=UNCONFIRMED&datasets=VERIFIED&datasets=CLOSED&datasets=RESOLVED All]
 +
|[https://bugs.eclipse.org/bugs/reports.cgi?product=JGit&datasets=NEW&datasets=REOPENED&datasets=UNCONFIRMED&datasets=VERIFIED&datasets=CLOSED&datasets=RESOLVED All]
 +
|-
 +
!Lists
 +
!EGit
 +
!JGit
 +
|-
 +
| <span style="color:red">Unresolved for passed target milestones</span>
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?f1=OP&list_id=7727637&f0=OP&classification=Technology&f4=CP&query_format=advanced&j1=OR&f3=CP&f2=everconfirmed&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=EGit&target_milestone=0.10.0&target_milestone=0.10.0-M1&target_milestone=0.10.0-M2&target_milestone=0.10.0-M3&target_milestone=0.11&target_milestone=0.11-M1&target_milestone=0.11-M2&target_milestone=0.12&target_milestone=0.12-M1&target_milestone=0.12-M2&target_milestone=0.6.0-M1&target_milestone=0.6.0-M2&target_milestone=0.6.0-M3&target_milestone=0.7.0&target_milestone=0.8.0&target_milestone=0.9.0&target_milestone=0.9.0-M1&target_milestone=0.9.0-M2&target_milestone=0.9.0-M3&target_milestone=1.0.0&target_milestone=1.1&target_milestone=1.1-M1&target_milestone=1.1-M2&target_milestone=1.1-M3&target_milestone=1.2&target_milestone=1.2-M1&target_milestone=1.2-M2&target_milestone=1.3&target_milestone=1.3-M1&target_milestone=2.0&target_milestone=2.0-M1&target_milestone=2.0-M2&target_milestone=2.1&target_milestone=2.1-M1&target_milestone=2.2&target_milestone=2.2-M1&target_milestone=2.2-M2&target_milestone=2.3&target_milestone=2.4&target_milestone=3.0&target_milestone=3.0.1&target_milestone=3.0.2&target_milestone=3.1&target_milestone=3.2 Open]
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?f1=OP&list_id=7727591&f0=OP&classification=Technology&f4=CP&query_format=advanced&j1=OR&f3=CP&f2=everconfirmed&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=JGit&target_milestone=0.10.0&target_milestone=0.10.0-M1&target_milestone=0.10.0-M2&target_milestone=0.10.0-M3&target_milestone=0.11&target_milestone=0.11-M1&target_milestone=0.11-M2&target_milestone=0.12&target_milestone=0.12-M1&target_milestone=0.12-M2&target_milestone=0.6.0&target_milestone=0.7.0&target_milestone=0.8.0&target_milestone=0.9.0&target_milestone=0.9.0-M1&target_milestone=0.9.0-M2&target_milestone=0.9.0-M3&target_milestone=1.0.0&target_milestone=1.1&target_milestone=1.1-M1&target_milestone=1.1-M2&target_milestone=1.1-M3&target_milestone=1.2&target_milestone=1.2-M1&target_milestone=1.2-M2&target_milestone=1.3&target_milestone=1.3-M1&target_milestone=2.0&target_milestone=2.0-M1&target_milestone=2.0-M2&target_milestone=2.1&target_milestone=2.1-M1&target_milestone=2.2&target_milestone=2.2-M1&target_milestone=2.2-M2&target_milestone=2.3&target_milestone=2.4&target_milestone=3.0&target_milestone=3.0.2&target_milestone=3.1&target_milestone=3.2 Open]
 +
|-
 +
| Open bugs
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?product=EGit&bug_status=NEW&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&order=bug_severity Open]
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?product=JGit&bug_status=NEW&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&order=bug_severity Open]
 +
|-
 +
| Open enhancements
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?product=EGit&bug_status=NEW&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_severity=enhancement&order=bug_severity Open]
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?product=JGit&bug_status=NEW&bug_status=REOPENED&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_severity=enhancement&order=bug_severity Open]
 +
|-
 +
| Bugs with votes
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?f1=votes&list_id=2849777&columnlist=votes%2Cproduct%2Ccomponent%2Cassigned_to%2Cbug_status%2Cresolution%2Cshort_desc%2Cchangeddate&o1=greaterthan&resolution=---&v1=1&classification=Technology&query_format=advanced&product=EGit With Votes]
 +
| [https://bugs.eclipse.org/bugs/buglist.cgi?f1=votes&list_id=2849777&columnlist=votes%2Cproduct%2Ccomponent%2Cassigned_to%2Cbug_status%2Cresolution%2Cshort_desc%2Cchangeddate&o1=greaterthan&resolution=---&v1=1&classification=Technology&query_format=advanced&product=JGit With Votes]
 +
|-
 +
|Assigned bugs and enhancements
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?product=EGit&bug_status=ASSIGNED&order=bug_severity Assigned]
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?product=JGit&bug_status=ASSIGNED&order=bug_severity Assigned]
 +
|-
 +
! Reports
 +
! colspan=2 | EGit and JGit
 +
|-
 +
| Open EGit and JGit bugs
 +
| colspan=2 | [https://bugs.eclipse.org/bugs/report.cgi?y_axis_field=bug_status&cumulate=1&format=bar&x_axis_field=product&query_format=report-graph&short_desc_type=allwordssubstr&product=EGit&product=JGit&longdesc_type=allwordssubstr&bug_file_loc_type=allwordssubstr&status_whiteboard_type=allwordssubstr&keywords_type=allwords&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=REOPENED&bug_status=ASSIGNED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&emailtype2=substring&bug_id_type=anyexact&chfieldto=Now&action=wrap&field0-0-0=noop&type0-0-0=noop Open]
 +
|-
 +
| Assigned EGit and JGit bugs
 +
| colspan=2 | [https://bugs.eclipse.org/bugs/report.cgi?y_axis_field=bug_status&cumulate=1&format=bar&x_axis_field=product&query_format=report-graph&short_desc_type=allwordssubstr&product=EGit&product=JGit&longdesc_type=allwordssubstr&bug_file_loc_type=allwordssubstr&status_whiteboard_type=allwordssubstr&keywords_type=allwords&bug_status=ASSIGNED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&emailtype2=substring&bug_id_type=anyexact&chfieldto=Now&action=wrap&field0-0-0=noop&type0-0-0=noop Assigned]
 +
|-
 +
| New bugs opened
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1d&chfieldto=Now&chfield=%5BBug+creation%5D&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last day]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1w&chfieldto=Now&chfield=%5BBug+creation%5D&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last week]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1m&chfieldto=Now&chfield=%5BBug+creation%5D&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last month]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1y&chfieldto=Now&chfield=%5BBug+creation%5D&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last year]
 +
|-
 +
| Bugs closed
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1d&chfieldto=Now&chfield=bug_status&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last day]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1w&chfieldto=Now&chfield=bug_status&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last week]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1m&chfieldto=Now&chfield=bug_status&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last month]
 +
| [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=bug_status&y_axis_field=product&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=EGit&product=JGit&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=-1y&chfieldto=Now&chfield=bug_status&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= Last year]
 +
|}
 +
 
 +
<br/>
 +
 
 +
To get notified of bugs, go to your e-mail preferences and add <product>.<component>-inbox@eclipse.org to your watch list. For example to get notified of EGit UI bugs, add ''egit.ui-inbox@eclipse.org''.
 +
 
 +
==  Keywords ==
 +
To simplify bug management we started to tag EGit bugs with additional pseudo keywords (not normal Bugzilla keywords). The tags are prepended to the bug's summary field. Since we use these tags for internal bug management reporters of a bug should not add any pseudo keywords when filing the bug. The owner of the component bucket is responsible to add the keywords.
 +
 
 +
Keywords are used to group bugs without assigning them to a developer. So with the introduction of the keywords it is easy to search for all bugs belonging to a specific sub component. For example to get an overview of all open refactoring issues search for new, assigned or reopened bugs containing the word [refactoring] in the summary field.
 +
 
 +
Be aware that not all bugs are tagged with keywords, only bugs that belong to a certain sub group may have a tag attached. The following lists some of the currently used tags.
 +
 
 +
{| cellpadding="3" cellspacing="0" border="1"
 +
!Tag
 +
!Description
 +
!Link
 +
|-
 +
|[sync]
 +
|everything related to Synchronize / Synchronize View
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?short_desc=%5Bsync%5D;query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;short_desc_type=allwordssubstr;product=EGit View bugs]
 +
|-
 +
|[repoView]
 +
|everything related to the Git Repository View
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?short_desc=%5BrepoView%5D;query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;short_desc_type=allwordssubstr;product=EGit View bugs]
 +
|-
 +
|[releng]
 +
|everything related to release engineering and build
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?short_desc=%5Breleng%5D;query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;short_desc_type=allwordssubstr;product=EGit View bugs]
 +
|-
 +
|[historyView]
 +
|everything related to the Git History View
 +
|[https://bugs.eclipse.org/bugs/buglist.cgi?short_desc=%5BhistoryView%5D;query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;short_desc_type=allwordssubstr;product=EGit View bugs]
 +
|}
 +
 
 +
<br/>
 +
 
 +
== Spam Bugs ==
 +
If you come across spam bugs you can request webmaster to delete them by marking them as duplicate of bug 442999.
 +
 
 +
Also see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=502814 bug 502814]
  
 
= Website =
 
= Website =
  
The EGit and JGit websites are located in a CVS repository on the Eclipse Foundation's servers.
+
The EGit and JGit websites are located in Git repositories which are configured for Gerrit code review.
 +
 
 +
'''egit'''
  
''egit''  
+
*File &gt; Import &gt; Git &gt; Projects from Git
 +
* Select URL
 +
** HTTPS protocol: '''https://git.eclipse.org/r/p/www.eclipse.org/egit.git'''
 +
** SSH protocol: '''ssh://user@git.eclipse.org:29418/www.eclipse.org/egit.git'''
 +
* in Repositories View on node "origin" click "Gerrit Configuration..." and select branch "master", then changes you push to upstream will end up in Gerrit for review and can be submitted there
  
*File &gt; Import &gt; CVS &gt; Projects from CVS
+
'''jgit'''
*Select URL ''':pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse'''  
+
*Use module '''egit''' (from '''www''')
+
*Finish
+
  
''jgit''  
+
*File &gt; Import &gt; Git &gt; Projects from Git
 +
* Select URL
 +
** HTTP protocol: '''https://git.eclipse.org/r/p/www.eclipse.org/jgit.git'''
 +
** SSH protocol: '''ssh://user@git.eclipse.org:29418/www.eclipse.org/jgit.git'''
 +
* in Repositories View on node "origin" click "Gerrit Configuration..." and select branch "master", then changes you push to upstream will end up in Gerrit for review and can be submitted there
  
*File &gt; Import &gt; CVS &gt; Projects from CVS
+
<br/>
*Select URL ''':pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse'''
+
*Use module '''jgit''' (from '''www''')
+
*Finish
+
  
 
= Contributing Patches  =
 
= Contributing Patches  =
  
Review the following style guides:
+
== Using Gerrit at Eclipse ==
  
*[http://egit.eclipse.org/w/?p=jgit.git;a=blob;f=SUBMITTING_PATCHES;hb=HEAD JGit SUBMITTING_PATCHES]  
+
EGit and JGit projects are using [https://www.gerritcodereview.com/ Gerrit Code Review] for Git based patch submission and review.  
*[http://egit.eclipse.org/w/?p=egit.git;a=blob;f=SUBMITTING_PATCHES;hb=HEAD EGit SUBMITTING_PATCHES]
+
  
Currently the project is alpha-testing [http://code.google.com/p/gerrit/ Gerrit Code Review] for Git based patch submission and review. To use the alpha testing instance hosted at eclipse.org:
+
Parts of this chapter are also available in the [https://wiki.eclipse.org/Gerrit#Doing_Code_Reviews_with_Gerrit Eclipse Gerrit wiki].
  
*[http://egit.eclipse.org/register Register a user account]  
+
Both projects can 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.
*Use ''Register New Email'' to register your email address with our Gerrit Code Review server. This step is required to validate the address is correct.  
+
 
*Add one or more public SSH keys  
+
=== User Account ===
 +
*In order to contribute you need an [https://dev.eclipse.org/site_login/createaccount.php Eclipse user account] on eclipse.org, on creation of a new account you must agree to the Contributor Agreement.
 +
 
 +
=== Legal Paperwork ===
 +
 
 +
Before your first contribution can be accepted, you need to electronically sign the [https://www.eclipse.org/legal/ECA.php Eclipse Contributor Agreement] (ECA). The ECA is good for three years. Find more information in the [https://www.eclipse.org/legal/ecafaq.php 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 [https://www.eclipse.org/projects/handbook/#ip-copyright-headers 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 [https://dev.eclipse.org/mhonarc/lists/eclipse.org-committers/msg00973.html requires a CQ], use one of the following git commands to check:
 +
* If it's committed: <tt>git log --shortstat</tt>
 +
* If not committed: <tt>git diff --stat</tt>
 +
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 [https://wiki.eclipse.org/Development_Resources/Contributing_via_Git Contributing via Git (for contributors)] and [https://wiki.eclipse.org/Development_Resources/Handling_Git_Contributions Handling Git Contributions (for committers)].
 +
 
 +
=== Logon ===
 +
 
 +
====Gerrit Web UI====
 +
Logon to the Gerrit Web UI at <code>https://git.eclipse.org/r/</code> using the email address you registered with your Eclipse (and Bugzilla) account and your Eclipse password.
 +
 
 +
====Git over SSH====
 +
When accessing Gerrit over SSH from git or EGit use the username displayed [https://git.eclipse.org/r/#/settings/ here] and upload your public SSH key to Gerrit [https://git.eclipse.org/r/#/settings/ssh-keys here].
 +
 
 +
Gerrit SSH URl: <code>ssh://username@git.eclipse.org:29418/egit/egit.git</code>
 +
 
 +
====Git over HTTPS====
 +
When accessing Gerrit over HTTPS from git or EGit use username and HTTP password displayed [https://git.eclipse.org/r/#/settings/http-password here]
 +
 
 +
Gerrit HTTPS URl: <code>https://git.eclipse.org/r/p/egit/egit.git</code>
 +
 
 +
=== SSH Keys ===
 +
* Add one or more public SSH keys to [https://git.eclipse.org/r/#/settings/ssh-keys Gerrit here]. 
 +
* If you are '''absolutely certain''' you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you [https://help.github.com/working-with-key-passphrases use a passphrase].
 +
* '''Generating SSH key pair on command line'''
 +
<pre style="width: 60em;">ssh-keygen -t rsa -C "your_email@youremail.com"</pre>
 
*Execute SSH once to accept the host key (or copy it from the registration web page)
 
*Execute SSH once to accept the host key (or copy it from the registration web page)
<pre style="width: 60em;">ssh -p 29418 username@egit.eclipse.org
+
<pre style="width: 60em;">ssh -p 29418 username@git.eclipse.org
 
</pre>  
 
</pre>  
*[http://egit.eclipse.org/r/#settings,new-agreement Confirm you agree] to the Eclipse.org Terms of Service by completing the Individual Contributor agreement.  
+
* [https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration Generating SSH key pair in Eclipse]
*Upload your patch from Git to the target project:  
+
 
**JGit
+
=== Doing Code Reviews with Gerrit ===
<pre style="width: 60em;">git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
+
*Visit the [https://git.eclipse.org/r/ Eclipse Gerrit Code Review instance] to start reviewing,
 +
*[https://git.eclipse.org/r/#/settings/projects Register to watch projects] if you want to be notified by email on new or updated changes pushed for review
 +
*Adjust your [https://git.eclipse.org/r/#/settings/preferences Gerrit preferences] to customize it to your needs
 +
*See the [https://git.eclipse.org/r/Documentation/index.html#_user_guide Gerrit user guide] for more information about using Gerrit.
 +
*The [https://wiki.eclipse.org/EGit/User_Guide#EGit_Tutorial_.28EclipseCon_Europe_Nov_2011.29 EGit tutorial] walks you through the basic steps of working with Gerrit and EGit.
 +
*Use [https://git.eclipse.org/r/Documentation/user-search.html Gerrit queries] to filter the review list for changes you are interested in:
 +
**[https://git.eclipse.org/r/#/q/status:open+project:egit/egit,n,z EGit changes pending in review]
 +
**[https://git.eclipse.org/r/#/q/status:open+project:jgit/jgit,n,z JGit changes pending in review]
 +
 
 +
=== Using Gerrit with git command line: ===
 +
*Upload your patch from Git to the target project:
 +
 
 +
'''JGit'''
 +
<pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/jgit/jgit.git HEAD:refs/for/master
 
</pre>  
 
</pre>  
**EGit
+
'''EGit'''
<pre style="width: 60em;">git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
+
<pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/egit/egit.git HEAD:refs/for/master
 
</pre>  
 
</pre>  
*Visit our [http://egit.eclipse.org/r/ Gerrit Code Review instance] to start reviewing
 
  
Or, create a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit new bug] and attach a Git formatted patch file, as produced by the `git format-patch` tool.
+
*Visit the [https://git.eclipse.org/r/ Eclipse Gerrit Code Review server] 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:
 +
<pre>cd path/to/jgit
 +
git config remote.review.url ssh://username@git.eclipse.org:29418/jgit/jgit.git
 +
git config remote.review.push HEAD:refs/for/master
 +
 
 +
cd path/to/egit
 +
git config remote.review.url ssh://username@git.eclipse.org:29418/egit/egit.git
 +
git config remote.review.push HEAD:refs/for/master
 +
</pre>
 +
You can now submit review requests from either repository using:
 +
<pre>git push review
 +
</pre>
 +
 
 +
=== Using Gerrit with EGit: ===
 +
Eclipse will look for your private key in the SSH2 Home location specified in the General&gt;Network Connections&gt;SSH2 Preference Page.
 +
* [[EGit/User_Guide#Cloning_Remote_Repositories | Clone the JGit and EGit repositories]] and select '''Gerrit Configuration...''' in the context menu of the remote "origin" in the Git Repositories view to [https://wiki.eclipse.org/EGit/User_Guide#Gerrit_Configuration 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)
 +
*** <code>ssh://username@git.eclipse.org:29418/(project).git</code> 
 +
** In the Ref mapping section, add a RefSpec specification of <code>HEAD:refs/for/master</code>
 +
 
 +
*Visit our [https://git.eclipse.org/r/ 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|Coding conventions]]
 +
 
 +
[[User_Interface_Guidelines|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 {{bug|457592}}.
 +
 
 +
=== 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 {{bug|414421}}.
 +
 
 +
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 [https://stackoverflow.com/questions/10413922/convert-spaces-to-tabs-in-lines-i-changed-in-a-commit?answertab=active#tab-top 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  ==
 
== Commit message guidelines  ==
  
*The commit message header should fit on one line and should start with an uppercase letter
+
*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 commit message have newline characters after every 60-70 characters.
+
*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: <code>UploadPack: Use reachability checker to validate non-advertised wants</code>
*If a Gerrit Change-Id is available (for example when re-submitting to the same change), it should be added in the format below
+
*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.  
*If there is an associated bug number in Bugzilla about it, it should come right before Gerrit's Change-Id entry (if available) or towards the end.  
+
*The first sentence should be a clear and concise description about the change.  
+
 
*Enter a newline before providing a more detailed description about the change.
 
*Enter a newline before providing a more detailed description about the change.
<pre>Fix the commit dialog to respect the workbench's selection
+
*Format the commit message to have newline characters after every 60-70 characters.
 +
*Find more reasoning about commit message formatting in [https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html "A Note About Git Commit Messages"]
 +
*''Commit message footers'' (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.
 +
**If there is an associated bug number in Bugzilla about it, it should come as a ''Bug:'' footer right before Gerrit's Change-Id entry (if available) or towards the end. Use exactly the capitalization "Bug", since the automatic linking mechanism to the bug database is case sensitive.
 +
**If a ''Contribution Questionnaire'' has been issued to initiate and track the review of contributed changes by the Eclipse Foundation's IP team the IPZilla bug number should be added as  ''CQ:'' footer in the format shown below
 +
**A ''Gerrit Change-Id'' footer 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 [[EGit/Contributor_Guide#Install_the_commit-msg_hook_in_your_repository|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.
 +
 
 +
 
 +
<pre>CommitDialog: Fix the commit dialog to respect the workbench's selection
  
 
Originally, the commit dialog would automatically check off all
 
Originally, the commit dialog would automatically check off all
Line 219: Line 826:
  
 
Bug: 12345
 
Bug: 12345
Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a</pre>
+
CQ: 6031
 +
Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a
 +
Signed-off-by: Your Name <your.email@example.org>
 +
</pre>
  
== Test before submitting ==
+
== License Header ==
  
* Run all existing tests. It does not take very long.
+
All new code files, including test code, must have a license header.
* Pay attention to the Java and Eclipse SDK baselines. EGit requires only Java5 and Eclipse 3.5. You cannot use API's that are newer. We often see breakages because Java 6 API's are used.
+
  
== Adding a remote  ==
+
'''JGit''' is licensed under the [https://www.eclipse.org/org/documents/edl-v10.php Eclipse Distribution License] which is a form of the [https://opensource.org/licenses/BSD-3-Clause 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 [https://www.eclipse.org/org/foundation/boardminutes/2009_09_16_Minutes.php meeting of the board in Sep 2009].
  
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:
+
The license and copyright header to be used for '''JGit''' is
<pre>cd path/to/jgit
+
git config remote.review.url ssh://username@egit.eclipse.org:29418/jgit.git
+
git config remote.review.push HEAD:refs/for/master
+
  
cd path/to/egit
+
/*
git config remote.review.url ssh://username@egit.eclipse.org:29418/egit.git
+
  * Copyright (c) YEAR CONTRIBUTOR[ and others]
git config remote.review.push HEAD:refs/for/master
+
  *
</pre>
+
  * This program and the accompanying materials are made available under the
You can now submit review requests from either repository using:  
+
  * terms of the Eclipse Distribution License v. 1.0 which is available at
<pre>git push review
+
  * https://www.eclipse.org/org/documents/edl-v10.php.
</pre>
+
  *
 +
  * SPDX-License-Identifier: BSD-3-Clause
 +
  */
  
== Sending patches by mail  ==
+
'''EGit''' is licensed under the [https://www.eclipse.org/legal/epl-2.0/ Eclipse Public License 2.0] and uses the license header
  
Although sending patches by mail is the approved way of interacting with, and asking feedback from, the Git project, please don't send patches via [http://www.kernel.org/pub//software/scm/git/docs/git-send-email.html git send-email]. Instead, please use [http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html git format-patch] to generate the <code>mbox</code>, and then attach that to an item in bugzilla as per the above SUBMITTING_PATCHES guides.  
+
/*******************************************************************************
 +
  * Copyright (c) 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:
 +
 
 +
<pre>Copyright (C) 2010, 2011 Some Name <some@example.org>
 +
</pre>
 +
 
 +
Change it like this (notice the updated year):
 +
 
 +
<pre>Copyright (C) 2010, YEAR Some Name <some@example.org> and others.
 +
</pre>
 +
 
 +
If there is a section <tt>Contributors:</tt> 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:
 +
 
 +
<pre>Copyright (C) 2010 Some Name <some@example.org>
 +
Copyright (C) 2011 Other Name <other@example.org>
 +
</pre>
 +
 
 +
Add another line:
 +
 
 +
<pre>Copyright (C) 2010 Some Name <some@example.org>
 +
Copyright (C) 2011 Other Name <other@example.org>
 +
Copyright (C) YEAR Your Name <you@example.org>
 +
</pre>
 +
 
 +
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  ==
  
If you're sending a work-in-progress for a review, be aware that you can also attach work-in-progress (or RFC) items to Bugzilla; it's not just for finished patches.  
+
EGit and JGit can accept patches only via Gerrit as per [[#Contributing_Patches]].
  
'''However''', it's generally preferred that you send items which you want comments on via Gerrit as per [[#Adding_a_remote]], since Gerrit allows comments to be added in-line and allows the opportunity to send multiple versions of a patch after changes are made. Once a change has been submitted to Gerrit, you can then mail the developer mailing list with a request to review your change via URL or get Gerrit to send the mail on your behalf.
+
<br/>
  
 
= Gerrit Code Review Cheatsheet  =
 
= Gerrit Code Review Cheatsheet  =
  
 
== Install the commit-msg hook in your repository  ==
 
== Install the commit-msg hook in your repository  ==
<pre style="width: 60em;">scp -p -P 29418 username@egit.eclipse.org:hooks/commit-msg .git/hooks/
+
<pre style="width: 60em;">scp -p -P 29418 username@git.eclipse.org:hooks/commit-msg .git/hooks/
 
</pre>  
 
</pre>  
 
This will ask for a password. It is the password that you have to generate in the ''SSH Keys'' section of settings in your Gerrit account.
 
This will ask for a password. It is the password that you have to generate in the ''SSH Keys'' section of settings in your Gerrit account.
  
You can alternatively [http://egit.eclipse.org/r/tools/hooks/commit-msg download the file]. The [http://gerrit.googlecode.com/svn/documentation/2.1.2/cmd-hook-commit-msg.html hook] helps append a Change-Id to your commit message.
+
You can alternatively [https://git.eclipse.org/r/tools/hooks/commit-msg download the file]. The [https://gerrit-review.googlesource.com/Documentation/cmd-hook-commit-msg.html hook] helps append a Change-Id to your commit message.
 +
 
 +
EGit can also generate a Gerrit Change-Id into your commit message both [[EGit/User_Guide#Commit_Message|manually]] or in an [[EGit/User_Guide#Gerrit_Configuration|automated]] way.
  
 
== To create a new change  ==
 
== To create a new change  ==
  
 
*JGit
 
*JGit
<pre style="width: 60em;">git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
+
<pre style="width: 60em;">git push origin HEAD:refs/for/master
 
</pre>  
 
</pre>  
 
*EGit
 
*EGit
<pre style="width: 60em;">git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
+
<pre style="width: 60em;">git push origin HEAD:refs/for/master
 
</pre>  
 
</pre>  
Or, if you've followed the instructions on [[#Adding_a_remote]] you can simply do:  
+
Or, if you've followed the instructions on [[#Adding_a_dedicated_remote]] you can simply do:  
 
<pre style="width: 60em;">git push review
 
<pre style="width: 60em;">git push review
</pre>  
+
</pre>
Since the current repository has the right definition for 'review', you won't need to remember the canonical push URL
+
  
 
== To update an existing change with a new commit  ==
 
== To update an existing change with a new commit  ==
<pre style="width: 60em;">git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
+
<pre style="width: 60em;">git push origin HEAD:refs/for/master
 
</pre>  
 
</pre>  
This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on [http://gerrit.googlecode.com/svn/documentation/2.0/user-changeid.html change-id lines] and [http://gerrit.googlecode.com/svn/documentation/2.0/user-upload.html#push_replace replacing changes].
+
This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on [https://git.eclipse.org/r/Documentation/user-changeid.html change-id lines] and [https://git.eclipse.org/r/Documentation/user-upload.html#push_replace replacing changes].
  
 
'''Note:''' To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).
 
'''Note:''' To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).
Line 282: Line 946:
 
Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.  
 
Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.  
  
If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, [http://egit.eclipse.org/r/2 http://egit.eclipse.org/r/2] shows the 'download' section for each patchset. In this case, it looks like:  
+
If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, [https://git.eclipse.org/r/2 https://git.eclipse.org/r/2] shows the 'download' section for each patchset. In this case, it looks like:  
  
*Patch Set 1 <code>git pull git://egit.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)</code>  
+
*Patch Set 1 <code>git pull origin refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)</code>  
*Patch Set 2 <code>git pull git://egit.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)</code>  
+
*Patch Set 2 <code>git pull origin refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)</code>  
*Patch Set 3 <code>git pull git://egit.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)</code>  
+
*Patch Set 3 <code>git pull origin refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)</code>  
*Patch Set 4 <code>git pull git://egit.eclipse.org/jgit refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)</code>
+
*Patch Set 4 <code>git pull origin refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)</code>
  
 
Performing a <code>git pull</code> will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a <code>git fetch</code> instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:  
 
Performing a <code>git pull</code> will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a <code>git fetch</code> instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:  
<pre>git fetch git://egit.eclipse.org/jgit refs/changes/02/2/3
+
<pre>git fetch origin refs/changes/02/2/3
git fetch git://egit.eclipse.org/jgit refs/changes/02/2/4
+
git fetch origin refs/changes/02/2/4
  
 
git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25
 
git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25
  
# or git diff d14cc6 43de8d
+
or git diff d14cc6 43de8d
</pre>  
+
</pre>
If you're doing this from within an already checked out project, you can do <code>git fetch origin</code> (or any other remote name in <code>.git/config}</code>.
+
  
 
Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run <code>git gc</code> or wait until this happens automatically.
 
Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run <code>git gc</code> or wait until this happens automatically.
 +
 +
== Trigger Jenkins build for a change ==
 +
 +
We have build jobs '''jgit.gerrit''' on https://ci.eclipse.org/jgit/, and '''egit.gerrit''' and '''egit-github.gerrit''' on https://ci.eclipse.org/egit/ which are triggered automatically when a new change or a new patchset for an existing change is pushed for review. These jobs will comment on the respective change when the build is started and when it's finished and vote on the change according to the build and test results.
 +
 +
Sometimes you may want to retrigger such a build e.g. because it may have failed due to some temporary problem.
 +
Committers can manually trigger these jobs in the following way:
 +
*Go to [https://ci.eclipse.org/jgit/gerrit_manual_trigger/ Trigger a Gerrit event manually] page
 +
*Search for a change you'd like to build
 +
*Select the patch set(s) you want to trigger
 +
*Press '''Trigger Selected''' button
 +
If you are not a committer and need to retrigger a build ask for that on the mailing list.
  
 
== To approve a change  ==
 
== To approve a change  ==
Line 308: Line 983:
 
== To add a reviewer  ==
 
== To add a reviewer  ==
  
Once you've pushed your commit to Gerrit for review, you can go to the web page (http://egit.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.  
+
Once you've pushed your commit to Gerrit for review, you can go to the web page (https://git.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.
 +
 
 +
It's usually not necessary to add any reviewers, it should be reviewed by the committers sooner or later. If this hasn't happened, you can look for people that did changes in the same area and add them as reviewers. It's also ok to comment on a change to "bump" its visibility.
  
 
== Code Review  ==
 
== Code Review  ==
Line 314: Line 991:
 
The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.  
 
The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.  
  
== IP Review  ==
+
== Submission Guidelines ==
 
+
The IP review category indicates whether or not the change has been properly logged under the [http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf eclipse IP process]. Under that process, any committer should mark his/her change +1 if they were the sole author of the change. For any other change, a committer should only mark +1 after ensuring the corresponding bug in Bugzilla has been updated with the iplog flag, or the corresponding CQ has been marked checkintocvs. For contributions from external contributors have a look at [http://www.eclipse.org/dsdp/tm/development/committer_howto.php#external_contrib the detailed rules]. A +1 vote is required to submit a change, while a -1 vote will block submission.
+
 
+
= Libraries from Orbit  =
+
  
== Import Team Project Set ==
+
We strive to use Gerrit to improve our understanding of the code base and improve quality.  
The simplest way to import the 3rd party libraries needed to compile JGit and Egit:
+
*Download the Team Project Set for [http://wiki.eclipse.org/images/9/9c/GitDependencies.psf git dependencies]
+
*File > Import > Team > Team Project Set
+
*Next
+
*Select the downloaded GitDependencies.psf
+
*logon with user "anonymous", leave password field blank
+
*Finish
+
  
== Manual Import ==
+
In order to ensure a proper review happens, some simple guidelines should be followed:
''org.easymock''
+
  
*File &gt; Import &gt; CVS &gt; Projects from CVS
+
* vote 0/-1 for not-ready-to-submit (AKA WIP) own proposals, +1 otherwise;
*Select URL ''':pserver:anonymous@dev.eclipse.org:/cvsroot/tools'''
+
* If a changeset is not-ready-to-submit, please put [RFC] or [DRAFT] in the message to let people know
*Use module '''org.eclipse.orbit/org.easymock'''
+
* let non-trivial changes be in review for at least 24 hours
*Finish
+
* if you want your changeset reviewed by someone, please add them as a reviewer
*Right click on the project &gt; Team &gt; Switch to another branch
+
*Select tag from following list
+
*Refresh Tags
+
*Versions &gt; v20090202-0900
+
  
''org.kohsuke.args4j''
+
== Tips & Tricks ==
  
*File &gt; Import &gt; CVS &gt; Projects from CVS
+
=== Class Loading Issues ===
*Select URL ''':pserver:anonymous@dev.eclipse.org/cvsroot/tools'''
+
*Use module '''org.eclipse.orbit/org.kohsuke.args4j'''
+
*Finish
+
*Right click on the project &gt; Team &gt; Switch to another branch
+
*Select tag from following list
+
*Refresh Tags
+
*Branches &gt; v2_0_12
+
  
''javax.servlet''
+
If you encounter strange class loading issues during runtime (e.g. on UI test executions) the following might help:
  
*File &gt; Import &gt; CVS &gt; Projects from CVS
+
Enable tracing in your launch configuration to get information how imported packages are resolved at runtime. Select the Tracing tab in your launch configuration, select "Enable tracing", select plug-in org.eclipse.osgi, select category resolver/wiring on the right side.
*Select URL ''':pserver:anonymous@dev.eclipse.org/cvsroot/tools'''
+
*Use module '''org.eclipse.orbit/javax.servlet'''
+
*Finish
+
*Right click on the project &gt; Team &gt; Switch to another branch
+
*Select tag from following list
+
*Refresh Tags
+
*Branches &gt; v2_5
+
  
 
[[Category:Draft_Documentation]]
 
[[Category:Draft_Documentation]]

Latest revision as of 08:33, 17 August 2021

Contents

Communication

Channel JGit EGit
Developer Mailing List JGit developer mailing list EGit developer mailing list
Build Notices Mailing List JGit build notices mailing list EGit build notices mailing list
Reporting Bugs File new JGit bug File new EGit bug
User Forum EGit User Forum


Automated Developer Setup

The fastest developer setup for contributing to JGit/EGit is to use the Eclipse Installer and the EGit project setup to prepare an Eclipse IDE for JGit/EGit:

  • download and unpack the Eclipse Installer
  • start the Eclipse Installer
  • select the advanced mode

Oomph-01-advanced-mode.png

  • if the right most icon in the bottom toolbar of the installer rotates, there is an update available for the installer, which should be installed before continuing
  • if you are behind a proxy, change the proxy settings from the toolbar at the bottom

Oomph -01a-proxy-settings.png

  • on the product page select "Eclipse IDE for Eclipse Committers" and click "Next"

Oomph-02-proxy-product-selection.png

  • on the project page select project "EGit" and click "Next"

Oomph-03-project-egit.png

  • on Variables page accept default target platform, to fine tune variables click "Show all variables", click "Next"
  • on the Confirmation page click "Finish"

Oomph-04-installer-progress.png

  • the installer installs the chosen IDE and starts it, as soon as the installer says "Press Finish to close the dialog" you can close the installer window
  • the newly installed IDE will automatically clone the JGit and EGit repositories and configure the workbench for JGit/EGit development. You can observe the setup progress in the toolbar, if necessary you can reopen the setup wizard by clicking its icon in the status bar

Oomph-05-eclipse-progress.png

  • when the setup finished the IDE should looks similar to this

Oomph-06-ide.png

If you want to improve the EGit project setup, check the setup file in tools\oomph\EGit.setup (in your newly cloned egit repository). You can find more information about Oomph at

Manual Developer Setup

Obtaining Sources

EGit and JGit are self hosted in Git. You can browse the repositories on the web: EGit, JGit

The first section below describes how to clone a repository and can be skipped if you have done this before. The next section lists the repositories and their URLs.

Cloning

On the command line

git clone <enter URL>

After that, import the projects into Eclipse using Import > Existing Projects into Workspace.

Using EGit (see download page)

First, verify that the default repository folder as set on the main Git preference page is to your liking.

Then, clone the repository and import the projects:

  • Open File > Import... and select Git > Projects from Git
  • Selet URI
  • Enter the URL (see next section)
  • Import existing projects into the workspace from the newly created working directory

Repositories

To develop EGit, the EGit and JGit repositories are needed, the others are optional. To develop JGit, only JGit is needed.

EGit

URL: https://git.eclipse.org/r/egit/egit.git

This is the main repository, where the standard EGit feature is developed. It contains the code for the UI and Eclipse integration.

JGit

URL: https://git.eclipse.org/r/jgit/jgit.git

This is the Java implementation of Git used by EGit, for working with Git repositories.

EGit GitHub Integration

URL: https://git.eclipse.org/r/egit/egit-github.git

EGit also provides tools for integrating with GitHub and Mylyn tasks.

For getting the dependencies, open the file org.eclipse.mylyn.github-feature/github.target (view on web) and select Set as Target Platfrom.

EGit PDE Tools

URL: https://git.eclipse.org/r/egit/egit-pde.git

EGit also provides tools for integrating with PDE Build and Eclipse RelEng Tools. If you are an Eclipse developer using PDE Build and/or the Eclipse RelEng tools you might be interesting in the following as well. Otherwise you might just skip this section.

In addition to the dependencies required for JGit and EGit you also need Eclipse PDE (>= 3.6.1) as well as org.eclipse.releng.tools in your target platform or checked out from Git in your workspaces.

Development IDE Configuration

Download and install the Eclipse package "Eclipse IDE for Eclipse Committers" or "Eclipse for RCP and RAP Developers" from here, if you don't already have it:

https://www.eclipse.org/downloads/packages/

Tools

To install all the necessary tools to work on EGit/JGit, there is a egit-developer-tools.p2f file which you can use as follows:

  • File > Import > Install > Install Software Items from File
  • Browse...
    • Go to the location of your egit repository, open the tools directory and select egit-developer-tools.p2f
    • Alternatively, if you only want to contribute to JGit, download the file from the above link and select it
  • All the items you don't already have should be selected automatically
  • Finish the wizard
  • Restart

Java Requirements

EGit and JGit have Java 8.0 and Eclipse Platform 4.6 (Neon) as minimum requirements, so dependencies to newer Java and platform versions must be avoided.

We are using API Tools Environment Descriptions (see changes for JGit and EGit) to facilitate detecting code which isn't working on Java 8. If you followed the instructions in the Tools section above, the necessary descriptions should already be installed. Otherwise install API Tools Environment Descriptions from the release train repository, see Installing Execution Environment Descriptions.

Dependencies

After importing the EGit and JGit projects in Eclipse, they will not compile due to missing dependencies. Set a Target Platform to fix this

EGit target platforms in org.eclipse.egit.target
  • Open the org.eclipse.egit.target project
  • Choose the egit-<version>.target file matching the version of your Eclipse platform (e.g. 4.5 for Mars) and open it (this may take a while as it downloads the indexes of the p2 repositories the target platform refers to)
  • In the resulting editor, click on the Set as Target Platform link at the top right (this may also take a while since it downloads the dependencies)

After that, the workspace should build cleanly. If not, try Project > Clean... > All. If this also doesn't help open Preferences > Plug-In Development > Target Platform, select the checked target platform and click "Reload..." this will flush PDE's bundle cache and re-download the artifacts listed in the target platform.

There are different target definitions, one for each version of Eclipse that EGit supports. The one you select will be the one that is started if you want to try out a feature or bug fix.

You can always switch between them to test on different Eclipse versions. E.g. when you are developing some major UI functionality, you should try it with the oldest supported Eclipse release to make sure it doesn't depend on API that is only available in later versions.

Running EGit from Eclipse

Now that everything builds, the next step is to run an Eclipse instance with the EGit/JGit code of the workspace:

  • Right click on the org.eclipse.egit.ui project
  • Debug As > Eclipse Application

This should create a new launch configuration and start a new nested Eclipse instance in debug mode. The created launch configuration can be edited, e.g. to change where the workspace of the nested Eclipse should be located.

The launch configuration can also be used in normal (non-debug) mode of course.

Also see the reference on eclipse application launchers.


Builds

The central EGit and JGit builds run on the Jenkins build infrastructure provided by the Eclipse foundation.

Prerequisites for the Maven build are

JGit

  • JGit can be built using Maven or Bazel
  • use Java 8 to run the JGit build
  • JGit packaging projects (Eclipse features and p2 repository) are built using Maven and Tycho.

EGit

  • EGit is built using Maven and Tycho.

Mailing Lists

If you're interested in following builds, please check out the following mailing lists:

Maven Build

To build JGit or EGit versions <= 5.12.0 maven must be run using Java 1.8. Ensure that environment variable JAVA_HOME points to a Java 1.8 installation.

EGit versions >= 5.12.1 can be built with any Java >= 1.8, but the build uses maven toolchain definitions. To run a local EGit build for these versions (including the 'master' branch, i.e. EGit nightly), you need to have a local file ~/.m2/toolchains.xml providing at least a JDK toolchain definition for "JavaSE-1.8":

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
   <toolchain>
      <type>jdk</type>
      <provides>
         <id>JavaSE-1.8</id>
         <version>1.8</version>
      </provides>
      <configuration>
         <jdkHome>/absolute/path/to/jdk1.8</jdkHome>
      </configuration>
   </toolchain>
   <toolchain>
      <type>jdk</type>
      <provides>
         <id>JavaSE-11</id>
         <version>11</version>
      </provides>
      <configuration>
         <jdkHome>/absolute/path/to/jdk11</jdkHome>
      </configuration>
   </toolchain>
</toolchains>

The jdkHome directory is the one that contains the bin directory in which there is the java executable.

If you can, include already a definition for a Java 11 toolchain as shown above. EGit and JGit may require a minimum of Java 11 in the not-too-distant future.

Building JGit with maven currently requires running maven with Java 1.8 in all cases.

  • Due to a limitation of Tycho it is not possible to mix pom-first and manifest-first builds in the same reactor build hence the pom-first JGit build has to run separately before the build for the manifest-first JGit packaging project.
  • The local maven builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
  • To run the build behind a firewall follow https://maven.apache.org/guides/mini/guide-proxies.html

Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):

[~/src/jgit] $ mvn clean install
[INFO] Scanning for projects...
...

[~/src/jgit] $ mvn -f org.eclipse.jgit.packaging/pom.xml clean install
[INFO] Scanning for projects...
...

[~/src/jgit] $ cd ../egit

[~/src/egit] $ mvn clean install
[INFO] Scanning for projects...
...

[~/src/jgit] $ cd ../egit-github

[~/src/egit-github] $ mvn clean install
[INFO] Scanning for projects...
...

The EGit build uses the JGit p2 repository to resolve jgit dependencies. For local builds the build assumes that egit and jgit source trees are located under a common parent folder. If this is not the case the path to the jgit p2 repository has to be injected via system property:

[~/src/egit] $ mvn clean install -Djgit-site=file:/path/to/jgit/org.eclipse.jgit.packaging/org.eclipse.jgit.repository/target/repository

in the same way you can configure a custom path for the build of egit-github to the egit p2 repository

[~/src/egit-github] $ mvn clean install -Degit-site=file:/path/to/egit/org.eclipse.egit.repository/target/repository

The Jenkins build uses (for SNAPSHOT builds):

[~/src/egit] $ mvn clean install -Djgit-site=https://repo.eclipse.org/content/unzip/snapshots.unzip/
                     org/eclipse/jgit/org.eclipse.jgit.repository/${JGIT_VERSION}/org.eclipse.jgit.repository-${JGIT_VERSION}.zip-unzip/

If you wan to build EGit for a specific Eclipse platform use the corresponding EGit target platform. For instance, to build for Eclipse 4.19 (2021-03), use the egit-4.19 target platform:

[~/src/egit] $ mvn -Dtarget-platform=egit-4.19 clean install

See the contents of bundle org.eclipse.egit.target for the available target platforms.

Upon a successful build, a p2 update site should be generated inside egit/org.eclipse.egit.repository/target/repository. If not, make sure the target platform has been downloaded from within Eclipse (Windows>Preferences>Plug-in Development>Target Platform). The default target platform defined in the maven build is currently Eclipse 4.6 (Neon). If you skip setting the system property target-platform the target platform for Eclipse 4.6 will be used. EGit built with that target platform can run on any Eclipse >= 4.6. If you choose a higher target platform, the EGit produced may not run on Eclipses older than the target platform version.

Dependencies and License Check

In order to update the list of dependencies run the dash-licenses Maven plugin

mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIES

then sort the entries in the file DEPENDENCIES and check for changes against the previous version. If necessary file CQs for new dependencies which are flagged restricted by the tool. See the Eclipse projects handbook.

Currently this tool requires Java 11, hence first build JGit/EGit using the Java version they require and then use Java 11 to run the license check.

JGit Bazel Build

Since Gerrit is built using Bazel a Bazel build was also implemented for JGit. This simplifies working on Gerrit features which also require changes in JGit.

bazel build :all
  • The following test labels are supported: api, attributes, dfs, diff, http, lfs, lfs-server, nls, notes, pack, patch, pgm, reftree, revplot, revwalk, storage, submodule, symlinks, transport, treewalk, util
  • To run all tests execute
bazel test //...
  • To run specific tests, using labels:
bazel test --test_tag_filters=api,dfs,revplot,treewalk //...
  • to rerun all tests ignoring cached test results execute
bazel test //... --cache_test_results=NO
  • to set number of concurrent test runs
bazel test //... --jobs=4
  • to debug a test run
bazel test --test_output=streamed --test_filter=<fully qualified test method> <test target>

e.g.

bazel test --test_output=streamed --test_filter=org.eclipse.jgit.api.GitConstructionTest.testClose //org.eclipse.jgit.test:org_eclipse_jgit_api_GitConstructionTest
  • to configure loggers for test runs edit org.eclipse.jgit.test/tst-rsrc/simplelogger.properties, see the slf4j SimpleLogger documentation
  • to run tests repeatedly use
bazel test --runs_per_test=3 <test target>
bazel build --java_toolchain //tools:error_prone_warnings_toolchain :all


Note that the Bazel build does not yet support building JGit OSGi bundles, Eclipse features and the p2 repository which are required to install JGit in Eclipse.

FindBugs and PMD

As part of the build, JGit and EGit run FindBugs and PMD to find issues.

Checking for JGit API Changes using API Baseline

The JGit projects have API tooling enabled. In order to use PDE API tools to get assistance with maintaining API changes and additions you need to set an API baseline:

  • download the p2 repository for the latest EGit release (which includes the JGit artifacts) to a local folder, e.g. ~/egit-releases/updates-4.9.1, find the p2 repository URLs here and download the p2 repository of the latest minor release (service releases don't change API) using the corresponding link in the last column of that table
  • in Eclipse click "Preferences > Plug-In Development > API Baselines", click "Add Baseline..." and define a new baseline (e.g. egit-4.9.1) and point it to the local copy of the corresponding EGit p2 repository.
  • the API tools will then raise warning/errors for all detected problems and provide quick fixes helping to resolve these problems
  • see the PDE API Tools User Guide for more details.

Signing and Publishing

EGit and JGit builds running on the JGit/EGit Jenkins instances are automatically signed (using the CBI eclipse-jarsigner-plugin) and published to the folder

master branch:         /home/data/httpd/download.eclipse.org/egit/updates-nightly
latest stable branch:  /home/data/httpd/download.eclipse.org/egit/updates-stable-nightly
  • To enable signing the maven profile eclipse-sign must be enabled via the option -P eclipse-sign in the respective build jobs running at https://ci.eclipse.org/egit/

Contribution to Release Train

The release train contribution for JGit and EGit is maintained in the git repository

ssh://git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git

in the file

egit.aggrcon

The release train build is coordinated on the cross-project-issues-dev mailing list


Documentation

JGit

The JGit project generates a project report and javadocs using a Maven site. This Maven site is deployed to https://download.eclipse.org/jgit/site/${project.version}. E.g. https://download.eclipse.org/jgit/site/4.4.1.201607150455-r/

Generating the site:

$ mvn site:site

Staging the site locally under ./target/staging:

$ mvn site:stage

If you can connect to build.eclipse.org over ssh (ask webmaster if you are a committer and need ssh access) you can deploy a local build of the site:

$ mvn site:deploy

The site is deployed under https://download.eclipse.org/jgit/site/${project.version}

To select the ssh key to use for deploying over ssh add the following section to your Maven settings.xml:

<server>
     <id>jgit.website</id>
     <username>username</username>
     <privateKey>${user.home}/.ssh/id_rsa</privateKey>
     <password>{<encrypted passphrase>}</password>
     <filePermissions>664</filePermission>
     <directoryPermissions>775</directoryPermissions>
     <configuration></configuration>
</server>

Password encryption for Maven is described in https://maven.apache.org/guides/mini/guide-encryption.html

To deploy the site from JGit HIPP (Hudson) at https://hudson.eclipse.org/jgit/ enable the Maven profile build-server and add the Maven goals site:site site:deploy.

If you uploaded the site for a new release update the index /home/data/httpd/download.eclipse.org/jgit/docs/latest/apidocs/index.html to refer to the new release's site.

EGit

The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using Mylyn WikiText to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the EGit User's Guide. Have a look at the Style Guidelines and Eclipse Documentation Style Guide to get some guidance on how to write good documentation. More on that can be found here.

The documentation is contained in the org.eclipse.egit.doc plug-in. The build-help.xml drives the generation of the help content. It is integrated into the maven build. The regular maven build of org.eclipse.egit.doc

$ mvn clean install 

will only package the help content committed to the egit repository. To update the help content by downloading the latest documentation from the wiki run

$ mvn clean install -Dupdate.egit.doc

Don't forget to check all the generated help pages and especially all hyperlinks and images before pushing the updated help to the code review system for inclusion into the continuous build.

The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.


Tests

JGit Unit Tests

The JGit unit tests are executed during the maven build. To run them from the Eclipse workbench use the launch configurations which are part of the sources of the test bundles'.

JGit HTTP Tests

The JGit HTTP tests in org.eclipse.jgit.http.test rely on the Jetty web container.

To run these tests from Eclipse the Jetty feature is needed. Use one of the target platforms as described in dependencies.

Alternatively, install "Jetty 9.4.20.v20190813" from https://download.eclipse.org/jetty/updates/jetty-bundles-9.x/9.4.20.v20190813/

EGit Core Tests

The EGit Core tests are executed during the maven build for the bundle org.eclipse.egit.core.test.

To run them from the Eclipse workbench use the launch configuration which is part of the sources of the test bundle org.eclipse.egit.core.test.

EGit UI Tests

The EGit UI tests are using SWTBot, using the 'SWTBot for Eclipse Testing' feature.

You need to install at least "SWTBot for Eclipse Testing" and "SWTBot IDE Feature":

Starting a UI test from Eclipse:

  • select the test class or test method
  • click Run As > SWTBot Test

Start-swtbot-test.png

Do not touch the mouse or keyboard when the UI test is running since this may disturb the UI test by e.g. moving the current focus to another window.

During Maven Build

The tests are executed in the integration-test phase of the default Maven lifecycle.

If you want to skip execution of UI tests (only execute core tests):

mvn -P skip-ui-tests clean install

If you want to skip all tests:

mvn clean install -Dmaven.test.skip=true

Auxilary testing tools

Any code, including testing code, does not always do what you expected it to. The most common failure is probably the failure to actually execute the part of the code you wanted to test. Code coverage tools like EclEmma can easily visualize what part of the code is being executed.

Bugs

If you are looking for bugs/enhancements to start contributing, they have the keyword "helpwanted" or "bugday":

EGit bugs with helpwanted or bugday

JGit bugs with helpwanted or bugday

Links

Filing Bugs

How to file bugs

File a bug

File a bug for a vulnerability

If you discovered a vulnerability you want to report

this will ensure that the discussion on the vulnerability is kept private between the reporter and the committer group until the project prepared a release fixing the vulnerability

Bug Reports and Links

Trends (bugs and enhancements) EGit JGit
Open by component (date range editable) Open Open
Open by status Open Open
Assigned Assigned Assigned
Open and closed by status All All
Lists EGit JGit
Unresolved for passed target milestones Open Open
Open bugs Open Open
Open enhancements Open Open
Bugs with votes With Votes With Votes
Assigned bugs and enhancements Assigned Assigned
Reports EGit and JGit
Open EGit and JGit bugs Open
Assigned EGit and JGit bugs Assigned
New bugs opened Last day Last week Last month Last year
Bugs closed Last day Last week Last month Last year


To get notified of bugs, go to your e-mail preferences and add <product>.<component>-inbox@eclipse.org to your watch list. For example to get notified of EGit UI bugs, add egit.ui-inbox@eclipse.org.

Keywords

To simplify bug management we started to tag EGit bugs with additional pseudo keywords (not normal Bugzilla keywords). The tags are prepended to the bug's summary field. Since we use these tags for internal bug management reporters of a bug should not add any pseudo keywords when filing the bug. The owner of the component bucket is responsible to add the keywords.

Keywords are used to group bugs without assigning them to a developer. So with the introduction of the keywords it is easy to search for all bugs belonging to a specific sub component. For example to get an overview of all open refactoring issues search for new, assigned or reopened bugs containing the word [refactoring] in the summary field.

Be aware that not all bugs are tagged with keywords, only bugs that belong to a certain sub group may have a tag attached. The following lists some of the currently used tags.

Tag Description Link
[sync] everything related to Synchronize / Synchronize View View bugs
[repoView] everything related to the Git Repository View View bugs
[releng] everything related to release engineering and build View bugs
[historyView] everything related to the Git History View View bugs


Spam Bugs

If you come across spam bugs you can request webmaster to delete them by marking them as duplicate of bug 442999.

Also see bug 502814

Website

The EGit and JGit websites are located in Git repositories which are configured for Gerrit code review.

egit

jgit


Contributing Patches

Using Gerrit at Eclipse

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

Parts of this chapter are also available in the Eclipse Gerrit wiki.

Both projects can 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.

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.

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).

Logon

Gerrit Web UI

Logon to the Gerrit Web UI at https://git.eclipse.org/r/ using the email address you registered with your Eclipse (and Bugzilla) account and your Eclipse password.

Git over SSH

When accessing Gerrit over SSH from git or EGit use the username displayed here and upload your public SSH key to Gerrit here.

Gerrit SSH URl: ssh://username@git.eclipse.org:29418/egit/egit.git

Git over HTTPS

When accessing Gerrit over HTTPS from git or EGit use username and HTTP password displayed here

Gerrit HTTPS URl: https://git.eclipse.org/r/p/egit/egit.git

SSH Keys

  • Add one or more public SSH keys to Gerrit here.
  • If you are absolutely certain 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 rsa -C "your_email@youremail.com"
  • Execute SSH once to accept the host key (or copy it from the registration web page)
ssh -p 29418 username@git.eclipse.org

Doing Code Reviews with Gerrit

Using Gerrit with git command line:

  • Upload your patch from Git to the target project:

JGit

git push ssh://username@git.eclipse.org:29418/jgit/jgit.git HEAD:refs/for/master

EGit

git push ssh://username@git.eclipse.org:29418/egit/egit.git HEAD:refs/for/master

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@git.eclipse.org:29418/jgit/jgit.git
git config remote.review.push HEAD:refs/for/master

cd path/to/egit 
git config remote.review.url ssh://username@git.eclipse.org:29418/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:

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 bug 457592.

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 bug 414421.

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[1].

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 footers (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.
    • If there is an associated bug number in Bugzilla about it, it should come as a Bug: footer right before Gerrit's Change-Id entry (if available) or towards the end. Use exactly the capitalization "Bug", since the automatic linking mechanism to the bug database is case sensitive.
    • If a Contribution Questionnaire has been issued to initiate and track the review of contributed changes by the Eclipse Foundation's IP team the IPZilla bug number should be added as CQ: footer in the format shown below
    • A Gerrit Change-Id footer 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.


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
CQ: 6031
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 (c) 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 (c) 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.


Gerrit Code Review Cheatsheet

Install the commit-msg hook in your repository

scp -p -P 29418 username@git.eclipse.org:hooks/commit-msg .git/hooks/

This will ask for a password. It is the password that you have to generate in the SSH Keys section of settings in your Gerrit account.

You can alternatively download the file. The hook helps append a Change-Id to your commit message.

EGit can also generate a Gerrit Change-Id into your commit message both manually or in an automated way.

To create a new change

  • JGit
git push origin HEAD:refs/for/master
  • EGit
git push origin HEAD:refs/for/master

Or, if you've followed the instructions on #Adding_a_dedicated_remote you can simply do:

git push review

To update an existing change with a new commit

git push origin HEAD:refs/for/master

This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on change-id lines and replacing changes.

Note: To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).

To compare bulk diffs using Git

Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.

If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, https://git.eclipse.org/r/2 shows the 'download' section for each patchset. In this case, it looks like:

  • Patch Set 1 git pull origin refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)
  • Patch Set 2 git pull origin refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)
  • Patch Set 3 git pull origin refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)
  • Patch Set 4 git pull origin refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)

Performing a git pull will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a git fetch instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:

git fetch origin refs/changes/02/2/3
git fetch origin refs/changes/02/2/4

git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25

or git diff d14cc6 43de8d

Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run git gc or wait until this happens automatically.

Trigger Jenkins build for a change

We have build jobs jgit.gerrit on https://ci.eclipse.org/jgit/, and egit.gerrit and egit-github.gerrit on https://ci.eclipse.org/egit/ which are triggered automatically when a new change or a new patchset for an existing change is pushed for review. These jobs will comment on the respective change when the build is started and when it's finished and vote on the change according to the build and test results.

Sometimes you may want to retrigger such a build e.g. because it may have failed due to some temporary problem. Committers can manually trigger these jobs in the following way:

  • Go to Trigger a Gerrit event manually page
  • Search for a change you'd like to build
  • Select the patch set(s) you want to trigger
  • Press Trigger Selected button

If you are not a committer and need to retrigger a build ask for that on the mailing list.

To approve a change

  • Click on Publish Comments
  • Vote with the radio buttons

To add a reviewer

Once you've pushed your commit to Gerrit for review, you can go to the web page (https://git.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.

It's usually not necessary to add any reviewers, it should be reviewed by the committers sooner or later. If this hasn't happened, you can look for people that did changes in the same area and add them as reviewers. It's also ok to comment on a change to "bump" its visibility.

Code Review

The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.

Submission Guidelines

We strive to use Gerrit to improve our understanding of the code base and improve quality.

In order to ensure a proper review happens, some simple guidelines should be followed:

  • vote 0/-1 for not-ready-to-submit (AKA WIP) own proposals, +1 otherwise;
  • If a changeset is not-ready-to-submit, please put [RFC] or [DRAFT] in the message to let people know
  • let non-trivial changes be in review for at least 24 hours
  • if you want your changeset reviewed by someone, please add them as a reviewer

Tips & Tricks

Class Loading Issues

If you encounter strange class loading issues during runtime (e.g. on UI test executions) the following might help:

Enable tracing in your launch configuration to get information how imported packages are resolved at runtime. Select the Tracing tab in your launch configuration, select "Enable tracing", select plug-in org.eclipse.osgi, select category resolver/wiring on the right side.

Back to the top