Sculptor

Development Environment

This document describes the development environment and the development / release process for the Sculptor project:

Installation

To develop Sculptor you need local installations of the following tools:

The installation and configuration of these tools is described in Sculptors installation guide.

Maven Repository Manager

To improve development experience it’s recommended to install a Maven repository manager like Sonatype Nexus. Instead letting the Sculptors Maven build access the external Maven repositories directly the repository manager is used as a proxy. This proxy greatly reduces the network access because all Maven artifacts are only retrieved once and then managed by the local repository manager.

Configuration

After the successfully installation (as described in Sculptors installation guide) some additional configurations are necessary.

Eclipse text file encoding

Sculptors code generator templates are implemented with Xtext template expressions. These templates are using special tag brackets (guillemets), for which the characters « (Unicode 00AB) and » (Unicode 00BB) are used. The downside with the guillemets used in the templates is that you will have to have a consistent encoding (here ISO-8859-1).

So it’s necessary to set the default encoding in Eclipse to ISO-8859-1 via “Preferences > General > Workspace > Text file encoding > ISO-8859-1”.

As mentioned here this encoding is used in the development of Xtext as well.

Maven settings.xml

The Maven “settings.xml” needs some customizations. This file may be found (depending on your OS) in:

In this file we have to make the following modifications:

Maven repository manager

To use a local Maven repository manager (here Nexus) for redirecting all requests to the Maven Central repository a Maven profile and corresponding <mirror/> settings are necessary, e.g.

<profiles>
  <profile>
    <id>nexus</id>
    <mirrors>
      <!--This sends all request for the dummy URL http://central to the local Nexus instance -->
      <mirror>
        <id>nexus</id>
        <mirrorOf>central</mirrorOf>
        <url>http://localhost:8081/nexus/content/groups/public/</url>
      </mirror>
    </mirrors>

    <!-- Enable redirection of Maven Central to local Nexus via mirror with dummy URL http://central -->
    <repositories>
      <repository>
        <id>central</id>
        <url>http://central</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
      </repository>
    </repositories>
   <pluginRepositories>
      <pluginRepository>
        <id>central</id>
        <url>http://central</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
      </pluginRepository>
    </pluginRepositories>
  </profile>
</profiles>

<activeProfiles>
  <!--make the profile active all the time -->
  <activeProfile>nexus</activeProfile>
</activeProfiles>

Usage of the local repository manager can be (temporarily) turned-off by disabling the coresponding Maven profile via the commandline option -P!nexus.

Deployment to GitHub

For deploying the Eclipse plugin to GitHub the GitHub user credentials have to be defined in the <servers/> section, e.g.

<servers>
  <server>
    <id>github</id>
    <username>your-username</username>
    <password>your-password</password>
  </server>
</servers>

The server ID is referenced by the GitHub site-maven-plugin used in the eclipse-repository project.

Deployment to Sonatype OSS Repository Hosting Service

For deploying the Maven plugin to Sonatypes OSS Repository Hosting (OSSRH) service the Sonatype user credentials have to be defined in the <servers/> section, e.g.

<servers>
  <server>
    <id>sonatype-nexus-snapshots</id>
    <username>your-username</username>
    <password>your-password</password>
  </server>
  <server>
    <id>sonatype-nexus-staging</id>
    <username>your-username</username>
    <password>your-password</password>
  </server>
</servers>

The server IDs are referenced by the distribution repositories defined the Sonatype oss-parent POM referenced in the sculptor-parent project.

Passphrase for code signing via GPG Maven plugin

For signing the Maven artifacts via the maven-gpg-plugin during the release build a Maven profile with the GPG passphrase has to be defined in the <profiles/> section, e.g.

<profile>
  <id>release-gpg-passphrase</id>
    <activation>
      <property>
        <name>performRelease</name>
        <value>true</value>
      </property>
    </activation>
  <properties>
    <gpg.passphrase>your-passphrase</gpg.passphrase>
  </properties>
</profile>

Source Code

Use Eclipses Git support EGit or any other Git client to clone Sculptors GitHub repository https://github.com/sculptor/sculptor, e.g.

$ git clone git://github.com/sculptor/sculptor.git
$ cd sculptor

Maven modules

The following is a brief overview of the main Maven modules of Sculptors source code:

Eclipse projects

Import all Maven projects in Eclipse (via Eclipse M2E) with “File > Import… > Existing Maven Projects”. For improved development experience organize the projects in appropriate Eclipse working sets.

After executing a Maven build from the commandline the corresponding projects in Eclipse have to be refreshed manually! Thereafter you should not have any red crosses (problems) in Eclipse. Sometimes, validation errors in code generation files (.xtend) must be cleaned manually as well. This an be done with a “clean build” (using “Project > Clean…”) of the corresponding Eclipse project.

Build

The following chapters are describing the different aspects of Sculptors Maven-based build process.

Build the whole project

Without specifying any Maven profile the whole project (without examples) is built:

mvn clean install

Build parts of the project

By specifying one or more from the following Maven profiles certain parts of the project are built:

E.g. to built the Maven stuff and the examples only then the following commands are used:

mvn clean install -Pmaven,examples

Development process

The project uses the gitflow workflow. So development of small features is done in the branch “develop”. Larger features are implemented within a feature branch (created via git flow feature start some-new-feature).

After finishing the new feature the feature branch is merged with “develop” via git flow feature finish some-new-feature.

Non-committers are not merging the feature branch with “develop” (within their forked repository) but pushing the feature branch to their GitHub repository and opening a pull request. After the pull request gets accepted the feature is merged in the “develop” branch of the Sculptor repository. From here the merged “develop” branch (with the feature) can be pulled in the forked repository.

The branch “master” is used for released code and the corresponding release tags only!

Release process

Sculptors release artifacts are hosted at different locations:

To release Sculptors Eclipse plugin and the Maven plugins (including the archetypes) we don’t use the (official) Maven release plugin but Atlassians Maven JGitFlow Plugin is used. It is based on and is a replacement for the maven-release-plugin enabling support for git-flow style releases via Maven.

Due to JGitFlows missing support for the Eclipse config files MANIFEST.MF and feature.xml (it only updates the version numbers in Maven POMs) we’re using the Tycho versions plugin for this.

So Sculptors release process is as follows:

To automate this process the script file release.sh is available. This script requires as arguments the release version and the next development version (without the suffix “-SNAPSHOT”), e.g. ./release.sh 3.0.0 3.0.1.

The following chapters are describing the deployment of the Eclipse plugin and the Maven plugin during the release build (executed via mvn jgitflow:release-finish).

Deployment of Eclipse p2 repository to GitHub

To deploy the Eclipse p2 repository (with the Sculptor Eclipse plugin) to GitHub the GitHub site-maven-plugin is used in the eclipse-repository project. The corresponding approach is described here.

Make sure that your Maven “settings.xml” contains the correct GitHub user credentials.

Deployment of Maven artifacts to Sonatypes OSS

To deploy artifacts to Maven Central the artifacts have to be staged on Sonatypes OSS Repository first. This is described in Sonatype OSS Maven Repository Usage Guide. The details of Sculptors access to this repository are outlined in the ticket OSSRH-5507).

Make sure that your Maven “settings.xml” contains the correct Sonatype user credentials.

Troubleshooting release finish

If the release script aborts with an error during execution of the Maven plugin maven-jgitflow-plugin:release-finish (as described in the corresponding ticket MJF-129) then the release process has to be finished manually:

  1. Use Git Flow to finish the release via git flow release finish <release name>.
  2. Push the release tag created by Git Flow to the GitHub repository via git push --tags.

  3. Change the version number in the develop branch to the next development version via

    mvn tycho-versions:set-version -P!all -DnewVersion=<release version>
mvn tycho-versions:set-version -P!all -DnewVersion=<next development version>-SNAPSHOT
git commit -a -m "updates POMs and MANIFST.MFs for development of version <next development version>-SNAPSHOT"

Publishing the staged release on Maven Central

After successfully finishing the release process Sculptors release artifacts are staged on Sonatypes OSS Maven Repository https://oss.sonatype.org/. To publish the artifacts on Maven Central the following has to be done:

  1. Login to Sonatype OSS Maven Repository Manager with the credentials mentioned in the ticket OSSRH-5507.
  2. Close the staged repository as described here.
  3. Release the closed repository as described here.

© Sculptor Team 2015 with help from Jekyll Bootstrap and Twitter Bootstrap

Fork me on GitHub