# Builds

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

- EGit Jenkins instance
- JGit Jenkins instance

Prerequisites for the Maven build are

- since 6.0 Java 11, older versions need Java 8
- at least Maven 3.5.2
- see settings.xml reference on how to do basic Maven configuration
- if you want to learn how Maven works start reading the Maven Getting Started Guide

## JGit

- JGit can be built using Maven or Bazel
- use Java 11 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:

- Subscribe to jgit-build@eclipse.org
- Subscribe to egit-build@eclipse.org

## 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 and < 6.0.0 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.

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.

Building JGit versions < 6.0.0 with maven requires running maven with Java 1.8 in all cases.

Building JGit versions >= 6.0.0 with maven requires running maven and compiling with at least Java 11.

- 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
- To run the JGit maven build on a case-insensitive file system, you might need to suppress javadoc generation if you get an error "class IO clashes with package of same name". Use "`mvn clean install -Dmaven.javadoc.skip=true`" instead of plain "`mvn clean install`".

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

We use the dash-licenses Maven plugin to check the license of 3rd party dependencies. See the Eclipse projects handbook.

On the master branch with the following changes the maven build is now running the license-check automatically

- jgit
- egit

A summary of the check results is written to the target/dash/summary file. Dependencies which need to be vetted are marked as restricted in this file.

It will fail the build if any dependency needs to be vetted:

    13:35:57  11:35:57 [INFO] --- license-tool-plugin:0.0.1-SNAPSHOT:license-check (license-check) @ egit-parent ---
    13:36:10  11:36:09 [INFO] Querying Eclipse Foundation for license data for 299 items.
    13:36:10  11:36:10 [INFO] Found 246 items.
    13:36:10  11:36:10 [INFO] License information could not be automatically verified for the following content:
    13:36:10  11:36:10 [INFO]
    13:36:10  11:36:10 [INFO] p2/orbit/p2.eclipse.feature/org.eclipse.emf.ecore/2.23.0.v20200630-0516
    13:36:10  11:36:10 [INFO]
    13:36:10  11:36:10 [INFO] This content is either not correctly mapped by the system, or requires review.
    13:36:10  11:36:10 [INFO] Summary file was written to: /home/jenkins/agent/workspace/egit.gerrit/repo/target/dash/summary
    13:36:10  11:36:10 [ERROR] Dependency license check failed. Some dependencies need to be vetted.

If that happens run the build again locally and provide a gitlab token with scope "api" to automatically create review requests for the IP team:

    mvn clean install -Ddash.iplab.token="<gitlab token>"

Then wait until these requests have been approved.

You can set the option dash.skip to skip the license check:

    mvn clean install -Ddash.skip

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

- 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 slf4j SimpleLogger documentation
- to run tests repeatedly use

    bazel test --runs_per_test=3 <test target>

- since 5.4.0 builds run with 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

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.

## Updating build version

use the tools/version.sh script to update the build version in all build files, e.g.

    ./tools/version.sh --snapshot=6.2.0-SNAPSHOT

## FindBugs and PMD

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

- JGit FindBugs Results
- JGit DRY (PMD) Results
- EGit FindBugs Results
- EGit DRY (PMD) Results

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

## Creating a release

Use the tools/release.sh script to create a new release, e.g.

    ./tools/release.sh v6.1.0.202203080745-r

- release versions have 5 parts

      major.minor.patch.buildTimestamp-qualifier

  - Traditionally we use local time in EST timezone for the buildTimestamp part of the version number since our build servers run in that timezone.
  - qualifier is

        m1,m2, ...

    for milestones,

        rc1, rc2, ...

    for release candidates and

        r

    for releases
- We sign release tags, follow Git Tools - Signing Your Work to set this up on your computer before creating the first release.
- 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.
- push the locally created release commit to git.eclipse.org for review
- wait for the verification build to succeed and vote +1 on verified
- review and submit the release change, then push the release tag to git.eclipse.org
- the CI job will build the release version and deploy it to the Eclipse Maven repo at repo.eclipse.org

### Release Notes

We create a release record for each release in the Eclipse project portal and publish release notes there.

- JGit releases
- EGit releases

### New and Noteworthy

For major and minor releases (e.g. 6.0.0, 6.3.0) we create a New and Noteworthy page

- JGit New and Noteworthy
- EGit New and Noteworthy

## Contribution to Release Train

We participate in the Eclipse simultaneous release and its schedule.

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 files

    simrel.aggr
    egit.aggrcon

Checkout the master branch and update the versions of jgit and egit to be contributed and the URL of the new version.

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 here. Old releases are moved to the archive server. Committers can trigger archiving on this page.

All these builds are deployed to the corresponding release repositories on nexus. Maven artefacts:

- jgit maven artefacts
- egit maven artefacts

Corresponding p2 repositories are exposed dynamically using the Nexus Unzip Plugin:

- jgit p2 repos
- egit p2 repos

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.

Open simrel.aggr using the CBI aggregator editor to edit these files. This editor knows the structure of these files and can check their validity.

Push the change for review, review and submit it when the verification build job has voted +1 on verified. 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.

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