1 <?xml version='
1.0' encoding='utf-
8'
?><!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns=
"http://www.w3.org/1999/xhtml">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8"/>
5 <title>EGit Contributor Guide - Builds
</title>
6 <link type=
"text/css" rel=
"stylesheet" href=
"../../book.css"/>
9 <table class=
"navigation" style=
"width: 100%;" border=
"0" summary=
"navigation">
11 <th style=
"width: 100%" align=
"center" colspan=
"3">Builds
</th>
14 <td style=
"width: 20%" align=
"left">
15 <a href=
"Running-EGit-from-Eclipse.html" title=
"Running EGit from Eclipse">
16 <img alt=
"Previous" border=
"0" src=
"../../images/prev.gif"/>
19 <td style=
"width: 60%" align=
"center"></td>
20 <td style=
"width: 20%" align=
"right">
21 <a href=
"Documentation.html" title=
"Documentation">
22 <img alt=
"Next" border=
"0" src=
"../../images/next.gif"/>
27 <td style=
"width: 20%" align=
"left" valign=
"top">Running EGit from Eclipse
</td>
28 <td style=
"width: 60%" align=
"center"></td>
29 <td style=
"width: 20%" align=
"right" valign=
"top">Documentation
</td>
31 </table><hr class=
"navigation-separator"/>
32 <h1 id=
"Builds">Builds
</h1>
33 <p>The central EGit and JGit builds run on the Jenkins build infrastructure provided by the Eclipse foundation.
</p>
36 <a href=
"https://ci.eclipse.org/egit/" target=
"egit_external">EGit Jenkins instance
</a>
39 <a href=
"https://ci.eclipse.org/jgit/" target=
"egit_external">JGit Jenkins instance
</a>
42 <p>Prerequisites for the Maven build are
</p>
44 <li>since
6.0 Java
11, older versions need Java
8 </li>
46 <a href=
"https://maven.apache.org/download.html" target=
"egit_external">at least Maven
3.5.2</a>
49 <a href=
"https://maven.apache.org/settings.html" target=
"egit_external">settings.xml reference
</a> on how to do basic Maven configuration
51 <li>if you want to learn how Maven works start reading
52 <a href=
"https://maven.apache.org/guides/getting-started/index.html" target=
"egit_external">the Maven Getting Started Guide
</a>
55 <h2 id=
"JGit_2">JGit
</h2>
57 <li>JGit can be built using Maven or Bazel
</li>
58 <li>use Java
11 to run the JGit build
</li>
59 <li>JGit packaging projects (Eclipse features and p2 repository) are built using Maven and Tycho.
</li>
61 <h2 id=
"EGit_2">EGit
</h2>
63 <li>EGit is built using Maven and Tycho.
</li>
65 <h2 id=
"Mailing_Lists">Mailing Lists
</h2>
66 <p>If you're interested in following builds, please check out the following mailing lists:
</p>
69 <a href=
"https://dev.eclipse.org/mailman/listinfo/jgit-build" target=
"egit_external">Subscribe to jgit-build@eclipse.org
</a>
72 <a href=
"https://dev.eclipse.org/mailman/listinfo/egit-build" target=
"egit_external">Subscribe to egit-build@eclipse.org
</a>
75 <h2 id=
"Maven_Build">Maven Build
</h2>
76 <p>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.
</p>
77 <p>EGit versions
>=
5.12.1 and
< 6.0.0 can be built with any Java
>=
1.8, but the build uses
78 <a href=
"https://maven.apache.org/guides/mini/guide-using-toolchains.html" target=
"egit_external">maven toolchain
</a> 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>
79 <b>~/.m2/toolchains.xml
</b></tt> providing at least a JDK toolchain definition for
"JavaSE-1.8":
81 <pre style=
"width: 55em;">
82 <?xml
version=
"1.0" encoding=
"UTF8"?
>
85 <type
>jdk
</type
>
87 <id
>JavaSE-
1.8</id
>
88 <version
>1.8</version
>
91 <jdkHome
>/absolute/path/to/jdk1.8
</jdkHome
>
92 </configuration
>
95 <type
>jdk
</type
>
97 <id
>JavaSE-
11</id
>
98 <version
>11</version
>
100 <configuration
>
101 <jdkHome
>/absolute/path/to/jdk11
</jdkHome
>
102 </configuration
>
106 <p>The
<tt>jdkHome
</tt> directory is the one that contains the
<tt>bin
</tt> directory in which there is the
<tt>java
</tt> executable.
</p>
107 <p>Also include a definition for a Java
11 toolchain as shown above: EGit versions
>=
6.0.0 require at least Java
11 to build, and require a Java
11 toolchain definition for running the tests.
</p>
108 <p>Building JGit versions
< 6.0.0 with maven requires running maven with Java
1.8 in all cases.
</p>
109 <p>Building JGit versions
>=
6.0.0 with maven requires running maven and compiling with at least Java
11.
</p>
112 <a href=
"https://wiki.eclipse.org/Tycho/How_Tos/Dependency_on_pom-first_artifacts" target=
"egit_external">limitation of Tycho
</a> 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.
114 <li>The local maven builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
</li>
115 <li>To run the build behind a firewall follow
116 <a href=
"https://maven.apache.org/guides/mini/guide-proxies.html" target=
"egit_external">https://maven.apache.org/guides/mini/guide-proxies.html
</a>
118 <li>To run the JGit maven build on a
119 <i>case-insensitive
</i> file system, you might need to suppress javadoc generation if you get an error
"class IO clashes with package of same name". Use
"<tt>mvn clean install -Dmaven.javadoc.skip=true</tt>" instead of plain
"<tt>mvn clean install</tt>".
122 <p>Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):
</p>
123 <pre style=
"width: 55em;">
124 [~/src/jgit] $ mvn clean install
125 [INFO] Scanning for projects...
128 [~/src/jgit] $ mvn -f org.eclipse.jgit.packaging/pom.xml clean install
129 [INFO] Scanning for projects...
132 [~/src/jgit] $ cd ../egit
134 [~/src/egit] $ mvn clean install
135 [INFO] Scanning for projects...
138 [~/src/jgit] $ cd ../egit-github
140 [~/src/egit-github] $ mvn clean install
141 [INFO] Scanning for projects...
144 <p>The EGit build uses the JGit p2 repository to resolve jgit dependencies. For local builds the build assumes
145 that egit and jgit source trees are located under a common parent folder. If this is not the case the path
146 to the jgit p2 repository has to be injected via system property:
</p>
147 <pre>[~/src/egit] $ mvn clean install -Djgit-site=file:/path/to/jgit/org.eclipse.jgit.packaging/org.eclipse.jgit.repository/target/repository
149 <p>in the same way you can configure a custom path for the build of egit-github to the egit p2 repository
</p>
150 <pre>[~/src/egit-github] $ mvn clean install -Degit-site=file:/path/to/egit/org.eclipse.egit.repository/target/repository
152 <p>The Jenkins build uses (for SNAPSHOT builds):
</p>
153 <pre>[~/src/egit] $ mvn clean install -Djgit-site=
<a href=
"https://repo.eclipse.org/content/unzip/snapshots.unzip/" target=
"egit_external">https://repo.eclipse.org/content/unzip/snapshots.unzip/
</a>
154 org/eclipse/jgit/org.eclipse.jgit.repository/${JGIT_VERSION}/org.eclipse.jgit.repository-${JGIT_VERSION}.zip-unzip/
156 <p>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:
</p>
157 <pre>[~/src/egit] $ mvn -Dtarget-platform=egit-
4.19 clean install
159 <p>See the contents of bundle
<code>org.eclipse.egit.target
</code> for the available target platforms.
</p>
160 <p>Upon a successful build, a p2 update site should be generated inside
161 <i>egit/org.eclipse.egit.repository/target/repository
</i>. 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.
163 <h2 id=
"Dependencies_and_License_Check">Dependencies and License Check
</h2>
164 <p>In order to update the list of dependencies run the dash-licenses Maven plugin
</p>
165 <pre style=
"width: 55em;">
166 mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIES -Ddash.projectId=technology.jgit
167 mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIES -Ddash.projectId=technology.egit
169 <p>for jgit and egit and then sort the entries in the file
<code>DEPENDENCIES
</code> and check for changes against the previous version.
170 If necessary file CQs for new dependencies which are flagged
171 <i>restricted
</i> by the tool.
173 <a href=
"https://www.eclipse.org/projects/handbook/#ip-license-tool" target=
"egit_external">Eclipse projects handbook
</a>.
175 <p>This tool requires Java
11.
</p>
176 <h2 id=
"JGit_Bazel_Build">JGit Bazel Build
</h2>
177 <p>Since Gerrit is built using
178 <a href=
"https://www.bazel.io/" target=
"egit_external">Bazel
</a> a Bazel build was also implemented for JGit.
179 This simplifies working on Gerrit features which also require changes in JGit.
183 <a href=
"https://www.bazel.io/versions/master/docs/install.html" target=
"egit_external">Install Bazel
</a>
185 <li>To build all libraries run
</li>
187 <pre>bazel build :all
190 <li>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
</li>
191 <li>To run all tests execute
</li>
193 <pre>bazel test //...
196 <li>To run specific tests, using labels:
</li>
198 <pre>bazel test --test_tag_filters=api,dfs,revplot,treewalk //...
201 <li>to rerun all tests ignoring cached test results execute
</li>
203 <pre>bazel test //... --cache_test_results=NO
206 <li>to set number of concurrent test runs
</li>
208 <pre>bazel test //... --jobs=
4
211 <li>to debug a test run
</li>
213 <pre>bazel test --test_output=streamed --test_filter=
<fully qualified test method
> <test target
>
216 <pre>bazel test --test_output=streamed --test_filter=org.eclipse.jgit.api.GitConstructionTest.testClose //org.eclipse.jgit.test:org_eclipse_jgit_api_GitConstructionTest
219 <li>to configure loggers for test runs edit org.eclipse.jgit.test/tst-rsrc/simplelogger.properties, see the
220 <a href=
"https://www.slf4j.org/api/org/slf4j/impl/SimpleLogger.html" target=
"egit_external">slf4j SimpleLogger documentation
</a>
222 <li>to run tests repeatedly use
</li>
224 <pre>bazel test --runs_per_test=
3 <test target
>
227 <li>since
5.4.0 builds run with
228 <a href=
"https://github.com/google/error-prone" target=
"egit_external">the errorprone static analyzer
</a> by default. If you want to enable it for older JGit versions execute
231 <pre>bazel build --java_toolchain //tools:error_prone_warnings_toolchain :all
233 <p>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.
</p>
234 <h2 id=
"Updating_build_version">Updating build version
</h2>
235 <p>use the tools/version.sh script to update the build version in all build files, e.g.
</p>
236 <pre style=
"width: 55em;">
237 ./tools/version.sh --snapshot=
6.2.0-SNAPSHOT
239 <h2 id=
"FindBugs_and_PMD">FindBugs and PMD
</h2>
240 <p>As part of the build, JGit and EGit run FindBugs and PMD to find issues.
</p>
243 <a href=
"https://ci.eclipse.org/jgit/job/jgit/findbugs" target=
"egit_external">JGit FindBugs Results
</a>
246 <a href=
"https://ci.eclipse.org/jgit/job/jgit/dry" target=
"egit_external">JGit DRY (PMD) Results
</a>
249 <a href=
"https://ci.eclipse.org/egit/job/egit/findbugs" target=
"egit_external">EGit FindBugs Results
</a>
252 <a href=
"https://ci.eclipse.org/egit/job/egit/dry" target=
"egit_external">EGit DRY (PMD) Results
</a>
255 <h2 id=
"Checking_for_JGit_API_Changes_using_API_Baseline">Checking for JGit API Changes using API Baseline
</h2>
256 <p>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:
</p>
258 <li>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
259 <a href=
"https://wiki.eclipse.org/EGit/FAQ#Where_can_I_find_older_releases_of_EGit.3F" target=
"egit_external">here
</a> 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
261 <li>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.
</li>
262 <li>the API tools will then raise warning/errors for all detected problems and provide quick fixes helping to resolve these problems
</li>
264 <a href=
"https://wiki.eclipse.org/PDE/API_Tools/User_Guide" target=
"egit_external">PDE API Tools User Guide
</a> for more details.
267 <h2 id=
"Signing_and_Publishing">Signing and Publishing
</h2>
268 <p>EGit and JGit builds running on the JGit/EGit Jenkins instances are automatically signed
270 <a href=
"https://wiki.eclipse.org/Common_Build_Infrastructure#Signing_tool" title=
"Common_Build_Infrastructure#Signing_tool" target=
"egit_external">CBI eclipse-jarsigner-plugin
</a>) and published to the folder
273 master branch: /home/data/httpd/download.eclipse.org/egit/updates-nightly
274 latest stable branch: /home/data/httpd/download.eclipse.org/egit/updates-stable-nightly
277 <li>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
278 <a href=
"https://ci.eclipse.org/egit/" target=
"egit_external">https://ci.eclipse.org/egit/
</a>
281 <h2 id=
"Creating_a_release">Creating a release
</h2>
282 <p>Use the tools/release.sh script to create a new release, e.g.
</p>
283 <pre style=
"width: 55em;">
284 ./tools/release.sh v6.1
.0.202203080745-r
287 <li>release versions have
5 parts
<pre>major.minor.patch.buildTimestamp-qualifier
</pre>
289 <li>Traditionally we use local time in EST timezone for the buildTimestamp part of the version number since our build servers run in that timezone.
</li>
290 <li>qualifier is
<pre>m1,m2, ...
</pre> for milestones,
<pre>rc1, rc2, ...
</pre> for release candidates and
<pre>r
</pre> for releases
</li>
293 <li>We sign release tags, follow
294 <a href=
"https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work" target=
"egit_external">Git Tools - Signing Your Work
</a> to set this up on your computer before creating the first release.
296 <li>We create all milestones and releases on a dedicated stable branch to avoid interference with ongoing development on master. E.g. use the stable-
6.1 branch for releasing
6.1.0 and subsequent patch releases like
6.1.1.
</li>
297 <li>push the locally created release commit to git.eclipse.org for review
</li>
298 <li>wait for the verification build to succeed and vote +
1 on verified
</li>
299 <li>review and submit the release change, then push the release tag to git.eclipse.org
</li>
300 <li>the CI job will build the release version and deploy it to the Eclipse Maven repo at repo.eclipse.org
</li>
302 <h3 id=
"Release_Notes">Release Notes
</h3>
303 <p>We create a release record for each release in the Eclipse project portal and publish release notes there.
</p>
306 <a href=
"https://projects.eclipse.org/projects/technology.jgit/governance" target=
"egit_external">JGit releases
</a>
309 <a href=
"https://projects.eclipse.org/projects/technology.egit/governance" target=
"egit_external">EGit releases
</a>
312 <h3 id=
"New_and_Noteworthy">New and Noteworthy
</h3>
313 <p>For major and minor releases (e.g.
6.0.0,
6.3.0) we create a New and Noteworthy page
</p>
316 <a href=
"https://wiki.eclipse.org/JGit/New_and_Noteworthy" target=
"egit_external">JGit New and Noteworthy
</a>
319 <a href=
"https://wiki.eclipse.org/EGit/New_and_Noteworthy" target=
"egit_external">EGit New and Noteworthy
</a>
322 <h2 id=
"Contribution_to_Release_Train">Contribution to Release Train
</h2>
323 <p>We participate in the
324 <a href=
"https://wiki.eclipse.org/Simultaneous_Release" target=
"egit_external">Eclipse simultaneous release
</a> and its
325 <a href=
"https://wiki.eclipse.org/Category:SimRel-2022-09" target=
"egit_external">schedule
</a>.
327 <p>The release train contribution for JGit and EGit is maintained in the git repository
</p>
328 <pre>ssh://git.eclipse.org/gitroot/simrel/org.eclipse.simrel.build.git
335 <p>Checkout the master branch and update the versions of jgit and egit to be contributed and the URL of the new version.
</p>
336 <p>Milestones (version ends with -m1, -m2, -m3) and release candidates (version ends with -rc1) are deployed on the download server to egit/staging/
<tag name
>, the final release (version ends with -r) goes to egit/updates-
<major version
>.
<minor version
>[.
<micro version
>]. The releases on the download server can be browsed
337 <a href=
"https://download.eclipse.org/justj/?file=egit" target=
"egit_external">here
</a>. Old releases are moved to the
338 <a href=
"https://archive.eclipse.org/justj/?file=egit" target=
"egit_external">archive server
</a>. Committers can trigger archiving
339 <a href=
"https://download.eclipse.org/egit/" target=
"egit_external">on this page
</a>.
341 <p>All these builds are deployed to the corresponding release repositories on nexus.
345 <a href=
"https://repo.eclipse.org/content/groups/releases/org/eclipse/jgit/" target=
"egit_external">jgit maven artefacts
</a>
348 <a href=
"https://repo.eclipse.org/content/groups/releases/org/eclipse/egit/" target=
"egit_external">egit maven artefacts
</a>
351 <p>Corresponding p2 repositories are exposed dynamically using the Nexus Unzip Plugin:
</p>
354 <a href=
"https://repo.eclipse.org/content/unzip/releases.unzip/org/eclipse/jgit/" target=
"egit_external">jgit p2 repos
</a>
357 <a href=
"https://repo.eclipse.org/content/unzip/releases.unzip/org/eclipse/egit/" target=
"egit_external">egit p2 repos
</a>
360 <p>Final releases of jgit are also deployed to Maven central using Sonatype's OSS Nexus using some scripts located in the jgit repository under tools/maven-central.
</p>
361 <p>Open simrel.aggr using the
362 <a href=
"https://wiki.eclipse.org/CBI/aggregator" target=
"egit_external">CBI aggregator editor
</a> to edit these files.
363 This editor knows the structure of these files and can check their validity.
365 <p>Push the change for review, review and submit it when the verification build job has voted +
1 on verified.
366 Note that the simultaneous release repository only accepts fast-forward submits. This means if another project's change has been submitted you may have to rebase your change.
</p>
367 <p>The release train build is coordinated on the
368 <a href=
"https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev" target=
"egit_external">cross-project-issues-dev mailing list
</a>.
372 </p><hr class=
"navigation-separator"/>
373 <table class=
"navigation" style=
"width: 100%;" border=
"0" summary=
"navigation">
375 <td style=
"width: 20%" align=
"left">
376 <a href=
"Running-EGit-from-Eclipse.html" title=
"Running EGit from Eclipse">
377 <img alt=
"Previous" border=
"0" src=
"../../images/prev.gif"/>
380 <td style=
"width: 60%" align=
"center">
381 <a href=
"Contributor-Guide.html" title=
"EGit Contributor Guide">
382 <img alt=
"EGit Contributor Guide" border=
"0" src=
"../../images/home.gif"/>
385 <td style=
"width: 20%" align=
"right">
386 <a href=
"Documentation.html" title=
"Documentation">
387 <img alt=
"Next" border=
"0" src=
"../../images/next.gif"/>
392 <td style=
"width: 20%" align=
"left" valign=
"top">Running EGit from Eclipse
</td>
393 <td style=
"width: 60%" align=
"center"></td>
394 <td style=
"width: 20%" align=
"right" valign=
"top">Documentation
</td>