This page is now hosted on https://odp.finos.org/docs/development-infrastructure/continuous-integration/java |
The Foundation hosts several Java projects already and provides a good level of support for building, testing and releasing Java code.
The most adopted (68% in 2016, according to RebelLabs) build tool for Java is Apache Maven, which provides a standard, modular, convention-based model to build and publish your Java projects; as such, the Foundation provides a Maven Module called Parent POM, containing build configurations that can be easily inherited by the single projects; in provides:
You can also adopt other Java build tools, such as gradle, ivy, ant or others, assuming that they are able to interact with the Central Repository.
Below are listed some of the most common processes that are involved in a Java project lifecycle and how they interact with the project infrastructure provided by the Foundation.
The build process aims to produce reusable Java binaries (in Maven terms, artifacts) in a reliable and reproducible way, from every contributor or consumer workstation; special build requirements should be documented in the project homepage.
The Maven command to build artifacts is mvn package.
All Java projects hosted by the Foundation are expected to use a groupId that is (or prefixed by) org.finos.<program name> and are published on the Central Repository (also known as Maven Central)
In order to publish artifacts (in Maven terms, artifact deployment), it's necessary to setup some accounts and configure the workstation accordingly; please note that these steps are not mandatory for all project teams, but only for those performing artifact deployment and releases (normally the project lead or a team member elected as release manager).
help@finos.org
, with the GitHub URL of your project, and your Sonatype Jira ID (from step 1)Locate (or create) and edit the settings.xml file in your local file-system to add a <server> item; using Maven encrypted passwords is strongly advised, to avoid setting up the password in clear text
<settings> <servers> <server> <id>ossrh</id> <username>[your-sonatype-jira-id]</username> <password>[your-sonatype-jira-pwd]</password> </server> <server> <id>ossrh-distro</id> <username>[your-sonatype-jira-id]</username> <password>[your-sonatype-jira-pwd]</password> </server> </servers> </settings> |
At this point, you can proceed with the deployment of the snapshot artifacts, by simply invoking mvn deploy
from the project root folder; as a result, artifacts will be publicly available on oss.sonatype.org and usable by anyone as Maven dependencies.
You can find more info on the Central Repository howto page for Maven.
A badge can be added at the top of the project's root-level README.md file, using the following Markdown syntax:
[![Maven Central](https://img.shields.io/maven-central/v/org.finos.<program name>/<project name>.svg?maxAge=2592000)](http://search.maven.org/#artifactdetails%7Corg.finos.<program name>%7C<project name>%7C2%7Cpom) |
This will appear as follows and link to the artifact on search.maven.org
If you want to run this process continuously for each commit, you can integrate with Travis CI or other Continuous Integration systems.
The Maven release process performs the following activities:
All the configurations documented in the section above (see snapshot deployment) also apply to the release process; additionally, it is required to:
Configure settings.xml by adding the following profile
<settings> ... <profiles> <profile> <id>ossrh</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <gpg.executable>gpg2</gpg.executable> </properties> </profile> </profiles> </settings> |
Test a snapshot deployment (see above), to make sure that you can authenticate against Sonatype servers
At this point you can proceed with the release:
export GPG_TTY=$(tty)
mvn release:prepare release:perform -Prelease
; the release profile will provide javadocs, sources and gpg signature configuration for the build; if you're not using ssf-parent-pom, you'd need to configure these plugins by yourself (this pom.xml may be useful)Upon release, your component will be published to Central: this typically occurs within 10 minutes, though updates to search can take up to two hours. You can also watch this youtube video to know more about the Nexus staging lifecycle.
If the release command fails with "gpg: signing failed: Inappropriate ioctl for device", run the following command and try again; more info on stackexchange.
export GPG_TTY=$(tty)
Maven allows to generate a documentation website in HTML format and provides different options to publish such content on remote servers; content is composed by:
The SSF Parent POM provides a configuration that allows to publish such content on the Symphony Program's GitHub Pages; to enable it, the build must be invoked using the -Ppublish-site Maven profile switch. For more info, follow the SSF Parent Pom documentation and check the Symphony Program's symphony-java-sample-bots project.