Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Gyrex/Contributor Guide

Gyrex
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse SourceProject Set File

A guide to contributing and committing to the Gyrex project.


Obtaining Source Code

Obtaining Source Code

Our regular (primary) SCM is Git. A list of available Git repositories can be found at git.eclipse.org/c/gyrex/. Contributions are welcome via Gerrit.

There are several ways to obtain a copy of each repository:

From the command line

 Git:
   git clone git://git.eclipse.org/gitroot/gyrex/gyrex-server
 
 or HTTP:
   git clone https://git.eclipse.org/r/gyrex/gyrex-server
 
 or SSH (authenticated):
   git clone ssh://<username>@git.eclipse.org:29418/gyrex/gyrex-server
 
 or HTTPS (authenticated):
   git clone https://<username>@git.eclipse.org/r/gyrex/gyrex-server

From an installed EGit plugin

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

Fork via GitHub

The folks at GitHub kindly setup mirrors of Eclipse Git repos at github.com/eclipse/. You may fork any repository you want there.

To compile properly you will also need to setup your Target Platform.

Website

The Gyrex web site is also maintained in Git. Contributions are welcome via Gerrit. The Eclipse Webmaster team maintains an infrastructures which publishes any commit automatically to all web servers.

 Git:
   git clone git://git.eclipse.org/gitroot/www.eclipse.org/gyrex

Workspace Setup

Here's how to set up your workspace for developing Gyrex.

Setup Eclipse

Download and install any Eclipse distribution suitable for developing Eclipse plug-ins. We recommend trying the latest Eclipse milestone for access to the latest features in JDT and PDE.

Required Plug-ins

  • Eclipse Plug-in Development Environment
  • Eclipse CVS Client
  • Eclipse Git Client

Required JDK

  • Download and install your preferred Java 6 JDK
  • Window -> Preferences -> Java -> Installed JREs -> Add... -> Standard VM -> Next
  • Set JRE home to the Java 6 JDK folder -> Finish
  • Activate check-box to set Java 6 JDK as the default JDK in Eclipse


Import Projects

Please use the "Import Existing Projects" wizard to import all Gyrex projects from any cloned Git repository. We also provide a collection of Working Sets for your convenience. Working Sets can be imported using the AnyEdit Tools plug-in available via Eclipse Marketplace. You can find the Working Sets file in the RelEng project (org.eclipse.gyrex.releng/devsupport/eclipse).

Setup Target Platform

We maintain a shared target platform. It's located in the "org.eclipse.gyrex.releng" project in the target folder.

  • Locate org.eclipse.gyrex.releng/target
  • Open file gyrex-dev.target in Target Definition editor
  • Wait till the target platform is resolved
  • Click on link "Set as Target Platform" (located in the upper right corner of the Target Definition editor)

Import Code Settings

Optimize Project Browsing

  • Switch to the Java perspective
  • Open the Package Explorer view menu (little triangle icon in the upper right corner) and select "Top Level Elements -> Working Sets"
  • Select all working sets ("Select All")
  • We recommend sorting the working sets (check "Sort working sets")
  • We also recommend hierarchical package browsing (open the Package Explorer view menu and this time select "Package Presentation -> Hierarchical")

Contributing Patches

We use Gerrit for reviewing and accepting patches. Please have a look at the Eclipse Gerrit Guide.


Commit message guidelines

  • The commit message header should fit on one line and should start with an uppercase letter. A blank line separates it from the body of the message.
    • If there is an associated bug in Bugzilla, the first line should start with Bug <number>:
  • The first line should be a clear and concise description about the change and should not end with a dot.
  • 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 in Bugzilla about it, it should come as a Task-Url: footer right before Gerrit's Change-Id entry (if available) or towards the end.
    • 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:" should be added at the end of the commit message (see example below) as per the Eclipse contribution guidelines
    • A "Also-by:" should be added for every additional author contributing/working on the commit
Bug 448274: Allow automatic mounting of applications

When an ApplicationProvider is published as a service, its properties
will be evaluated. The following properties will trigger an automatic
registration and mounting of an application.

  automount.url
    an url to mount the application on 
    (string, mandatory - no auto-mount if no url is set)
    
  automount.runtimeContextPath
    the context path 
    (String or IPath, defaults to /)
    
  automount.applicationId
    the id of the application to register
    (String, defaults to component.name value, 
    mandatory if component.name not defined)
    

Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=448274
Change-Id: I74f08b085cadc0f050888ac68c146b8dcfd9bbd7
Signed-off-by: Your Name <your.email@example.org>

Committer Resources

This article lists useful tips and articles for developers interested in working with/at the Gyrex code base.

Policies & Guidelines

API

The Eclipse Gyrex Project follows the Eclipse Project API guidelines. Please look at API Central and read the resources carefully. In case of any questions please don't hesitate to ask on gyrex-dev@eclipse.org mailing list.

Ramp Down Plan

Typically the last week of a Milestone is for testing, and fixing only regressions and P1 or blocking defects. For milestones, the component lead (or delegate) is enough to review and approve a bug.

For any M6 build, we plan to be API complete, so there will not be any more breaking API changes or unsolicited API change requests accepted.

After RC1 is produced, the time for general functional improvements is long past. The following describes the types of bugs that would be appropriate:

  • A regression
  • A P1 or P2 bug, one that is blocking or critical, and some cases of major severities.
  • Documentation and PII files are exceptions to the normal PMC required review, since there is little chance of that breaking anything, though it is still expected to be complete by M6, and remaining work to be only documentation fixes (that is, no refactoring of plugins, build changes, etc, without PMC review and approval).
  • In addition to a bug meeting the above priority/severity conditions, there should be a simple, safe, well understood fix that is well isolated from effecting other components, that doesn't affect API or adopters, that has been well reviewed and well tested.
  • As each Release Candidate passes, the criteria for weighing the benefit-to-risk ratio criteria gets higher and higher, and as such requires a larger number of project members to review.
    • After RC1: Another committer from the project must review and vote + using Bugzilla (see below).
    • After RC2: Another committer from the project and a project lead must review and vote +1 after reviewing the bug for appropriateness and risk.

Bugzilla Usage for RC Fixes

Committers can signify their approval for submitting fixes as required after RC1 by simply indicating +1 in a comment.

Bugzilla has a flag feature that is to be used for obtaining PMC approval. Enter the email address of the PMC member you are requesting approval from and submit. The PMC member is notified via email and will change the flag from '?' to '+' or '-' as appropriate.

Backporting fixes for service releases

  • Bugfixes should be backported to the maintenance branch only if they match the criteria above.
  • A review is required if bug fixes should be backported.
  • A patch must be attached to every bug which is backported.
  • If a bug has been backported for a service release, a tag of the form "srX_Y_Z" must be added to the status whiteboard field in bugzilla, where X_Y_Z is the service release number without dots (e.g. "sr0_10_1" for Gyrex 0.10.1).
  • To request backporting for a service release, a tag of the form "srX_Y_Z?" can be used.

See Also

Builds

Gyrex builds are produced on the Eclipse.org infrastructure. It's also possible to build locally. We use Maven and Tycho as our build technology which is also the standard build technology recommended by CBI.

Really Quick HowTo

# create temp directory
mkdir -p /tmp/gyrex
cd /tmp/gyrex

# clone source into local directory
git clone git://git.eclipse.org/gitroot/gyrex/gyrex-server.git .

# run Maven
mvn clean verify -f releng/aggregator/pom.xml

Prerequisites

The build is modular with build-order dependencies between the modules. We do not use a single "aggregator" project that aggregates the various Git repositories. But the build process expects that repositories are cloned into the same parent directory in order to allow relative path reference in build scripts/descriptor files.

Oracle Java 7 or higher

  • Oracle Java 7 JDK installed
    Note: Open JDK might work too but hasn't been tested yet. Feedback is welcome!
  • Environment variable JAVA_HOME set to the JDK directory
  • Please ensure that the java executable is available in the PATH!

Maven 3

  • Download from http://maven.apache.org/download.html or use your Linux distribution provided version (whether it works depends on the distribution).
    Note: At the time of writing, Maven 3.0.4 has been used and tested.
  • Please ensure that the mvn executable is available in the PATH!

Git

  • Please ensure that a recent version of the git executable is on the PATH!
  • Depending on your operating system the setup might vary. A good setup guide is available at Set Up Git (GitHub).


Building on Windows

In general, the build should also work on Windows. However, please be aware that there might be some limitations which make it a difficult to produce good results. For example, the path length is limited. Thus, the code tree should not be cloned into an exciting deep hierarchy of folders.

Additionally, builds on Windows can't produce the correct permissions in produced archives on Linux. Therefore, good quality builds for multiple platforms should not be produced from a Windows system.


Build Environment Setup

The following instructions are required to prepare your build environment. Unless otherwise stated, they apply to Linux, Mac OS X, and Windows platforms.

Maven Settings

To avoid getting hit by bug 365727 and to make sure your local environment configuration does not interfere with CBI build, make sure build user account does not have a Maven settings.xml

your_user@desktop:~$ ls -l ~/.m2/settings.xml
ls: cannot access /home/your_user/.m2/settings.xml: No such file or directory

On Windows XP this is located in:

C:\Documents and Settings\your_user\.m2\settings.xml
File should not exist, if it does delete it.

On Windows 7 this is located in:

C:\Users\your_user\.m2\settings.xml
File should not exist, if it does delete it.

Maven Memory Consumption

It may be necessary to grant Maven more memory. In this case, 2GB of RAM should be enough.

 export MAVEN_OPTS=-Xmx2048m

If you're using Windows:

 SET MAVEN_OPTS=-Xmx2048m


Cloning Gyrex Source Tree

All Gyrex Git repositories must be cloned into the same parent directory.

 git clone git://git.eclipse.org/gitroot/gyrex/gyrex-server.git


Running The Build

From the aggregator directory (directory 'releng/aggregator'), run:

 mvn clean verify

Multiple Streams

If you build multiple streams on the same system, you'll want to add '-Dmaven.repo.local=/some/directory/somewhere' to the end of each 'mvn' command to avoid collisions (using a different local repo for each stream). Most casual developers won't be affected.

Alternatively, you can add the additional argument to the MAVEN_OPTS environment variable instead.

On Windows use '-Dmaven.repo.local=C:\path\to\somewhere'.

Building directly from Eclipse

Instead of using Maven and Tycho, it is also possible to simply use the PDE Product Export wizard that's available in Eclipse. It requires to have the target platform configured and all Gyrex bundles imported in your workspace. The export can be started via File -> Export... -> Product configuration menu.

Gyrex-product-export.png

Note, however, that this is not recommended for producing official, production build results (to be published on Eclipse.org). But it's a convenient way of testing a product setup.


Build Process Insights

RelEng Project

The root for all build related stuff is the Gyrex RelEng (Release Engineering) tree. It contains:

git clone git://git.eclipse.org/gitroot/gyrex/gyrex-server.git 
cd gyrex-server/releng

Target Definition

The Target Definition is used for dependency management. All dependencies are listed as p2 repositories hosted at Eclipse.

Product Configuration and Features

The Product Configuration generates the various downloadable artifacts (eg. Gyrex Server ZIP). It references Eclipse Features which define collection of bundles that are meant to be build/deployed together. There are two types of features - regular Gyrex features and dependency-only features. Gyrex features collect Gyrex bundles. Dependency-only feature collect all dependencies. This makes it easy to customize Gyrex based products with different dependencies by using custom features.


Headless Build Process

The build process is entirely based on CBI. CBI is the common build infrastructure at Eclipse.org which is based on Maven and Tycho and has some additional Maven plug-ins for signing of bundles/binaries, etc.

We use Hudson for CI. The build process on Hudson is as follows:

  • Checkout all Git repos into same directory
  • Invoke Maven using releng/aggregator/pom.xml which will
    • Build target platform from target definition
    • Build modules referenced in POM
    • Assemble Gyrex Server Product
    • Produce final p2 Repo (including signing of artifacts when executed on Eclipse.org infrastructure with Maven profile)
    • Publish to download.eclipse.org (when executed on Eclipse.org infrastructure with Maven profile)

Hudson Build Jobs

The integration job is used for producing I, S and R builds. Care must be taken when producing S and R builds. The results are automatically published to download.eclipse.org (when running on Eclipse.org infrastructure).

The integration job is used for producing M and R builds of the maintenance branch.

Release Engineering

Please read through the following to get a better understanding of how releases are done.

Publishing Builds on download.eclipse.org

Builds get published automatically on download.eclipse.org. However, only I-Builds run automatically once per week. All other builds must be triggered manually.

Hudson: gyrex-latest

For producing development, milestone and major or minor release builds (no service releases).
https://hudson.eclipse.org/gyrex/job/gyrex-latest/

Parameter Description Integration Builds Milestone Builds Release Builds
BUILD_TYPE The type of a build. I S R
BUILD_IDENTIFIER A specific identifier to label the build or empty to generate a default one. (leave empty) upcoming minor release (eg. 1.3) plus suffix (eg. M1, M2, ... RC1, RC2...) without space (eg. 1.3M1, 2.0RC1, ...) major.minor for minor and major releases (eg. 1.3, 2.0); note: see below for service releases
BUILD_BRANCH The branch to build from. should always be master (until instructed/discussed otherwise)
PUBLISH_STREAM The stream this gets published to on download.eclipse.org/gyrex/$PUBLISH_STREAM/... should be the upcoming minor release (eg. 1.3) without last version component, just major.minor


Hudson: gyrex-maintenance

For producing service releases and maintenance builds out of the maintenance branch.
https://hudson.eclipse.org/gyrex/job/gyrex-maintenance/

Parameter Description Integration Builds Milestone Builds
BUILD_TYPE The type of a build. M R
BUILD_IDENTIFIER A specific identifier to label the build or empty to generate a default one. (leave empty) major.minor.service, i.e. exact release version of service releases (eg. 1.3.1, 2.0.1, 2.1.4)
BUILD_BRANCH The branch to build from. should be the "current" maintenance branch (eg. "maintenance/1.3" for 1.3.x builds)
PUBLISH_STREAM The stream this gets published to on download.eclipse.org/gyrex/$PUBLISH_STREAM/... should be the current minor release stream (eg. 1.3 for 1.3.x builds) without last version component, just major.minor


Performing a Release

The following outlines the steps necessary for producing a release.

Pre-Release Steps

  1. Publish a few milestone builds as release candidates (RC1, RC2, RC3 ...)

Update Maven Parent, Target Platform and child POMs to RELEASE version

  1. Update Maven pom.xml and remove -SNAPSHOT version suffix from:
    • gyrex-releng/mavenparent/pom.xml:
      • project -> version
      • project- > properties -> gyrex-target-platform.version
      • Important: if you find any other *.version property in project- > properties containing a -SNAPSHOT suffix you MUST abort here! Revert any changes, then update those versions to the release versions and start again with publishing and testing at least one additional RC (release candidate) build!
    • gyrex-releng/targetplatform/pom.xml:
      • project -> parent -> version
    • all other POMs used in the build:
      • cd $GYREX_SERVER_REPO_ROOT (if necessary)
      • mvn versions:update-child-modules -f releng/aggregator/pom.xml -DgenerateBackupPoms=false
  2. Test build locally
    • cd $GYREX_SERVER_REPO_ROOT (if necessary)
    • mvn clean package -f releng/aggregator/pom.xml
  3. Commit changes and push to upstream at eclipse.org

Build and Publish Release

  1. Trigger build of the following Hudson job:
    1. gyrex-latest
      • BUILD_TYPE: R
      • BUILD_IDENTIFIER: see tables above
      • BUILD_BRANCH and PUBLISH_STREAM as desired
  2. When builds are OK, create a release tag
    • cd $GYREX_SERVER_REPO_ROOT (if necessary)
    • git tag -a Rwhatever -m 'Release whatever'
    • Push tag to push to upstream at eclipse.org

Update Maven Parent, Target Platform and child POMs to next SNAPSHOT version

  1. Update Maven pom.xml and replace version with next.minor.0-SNAPSHOT version in:
    • gyrex-releng/mavenparent/pom.xml:
      • project -> version
      • project- > properties -> gyrex-target-platform.version
      • Update project- > properties -> comparator-repo.url to point to the just produced release (this is different than the -SNAPSHOT version)
    • gyrex-releng/targetplatform/pom.xml:
      • project -> parent -> version
    • all other POMs used in the build:
      • cd $GYREX_SERVER_REPO_ROOT (if necessary)
      • mvn versions:update-child-modules -f releng/aggregator/pom.xml -DgenerateBackupPoms=false
  2. Commit changes and push to upstream at eclipse.org

Create maintenance branch and update Hudson

Note: this must only be done on major and/or minor release. This step is not necessary for maintenance releases.

  1. Create maintenance branch based on tag created above
  2. Update Maven Parent, Target Platform and child POMs to next service SNAPSHOT version (just.released.version+1-SNAPSHOT)
    • Follow the exact same steps as in the previous section but this time on the maintenance branch using the next maintenance version
  3. Update the Hudson job configuration of gyrex-latest:
    • Set default of PUBLISH_STREAM parameter to new next.minor version
  4. Update the Hudson job configuration of gyrex-maintenance:
    • Set default of PUBLISH_STREAM parameter to the released current.minor version
    • Set default of BUILD_BRANCH parameter to the created maintenance/current.minor branch

Back to the top