|Mailing List • Forums • IRC|
|Browse Source • Project Set File|
A guide to contributing and committing to the Gyrex project.
This article lists useful tips and articles for developers interested in working with/at the Gyrex code base.
Our regular (primary) SCM is Git. A list of available Git repositories can be found at git.eclipse.org/c/gyrex/
There are several ways to obtain a copy of each repository:
From the command line
git clone http://git.eclipse.org/gitroot/gyrex/gyrex-platform.git gyrex-platform git clone http://git.eclipse.org/gitroot/gyrex/gyrex-admin.git gyrex-admin git clone http://git.eclipse.org/gitroot/gyrex/gyrex-releng.git gyrex-releng
From an installed EGit plugin
First, verify that the default repository folder as set on the main Git preference page is to your liking.
- File > Import > Git > Projects from Git
- Enter URI:
- Import existing projects into the workspace from the newly created working directory
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.
The Gyrex web site is also maintained in CVS. The Eclipse Webmaster team maintains an infrastructures which publishes any commit automatically to all web servers.
- Website CVS
Host: dev.eclipse.org Repository path: /cvsroot/org.eclipse Module: www/gyrex
Policies & Guidelines
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 firstname.lastname@example.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.
Here's how to set up your workspace for developing Gyrex.
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.
- Eclipse Plug-in Development Environment
- Eclipse CVS Client
- Eclipse Git Client
- 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
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 (
Setup Target Platform
We maintain a shared target platform. It's located in the "org.eclipse.gyrex.releng" project in the
- Open file
gyrex-dev.targetin 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")
Gyrex builds are produced on the Eclipse.org infrastructure. It's also possible to build locally.
The root for all build related stuff is the Gyrex RelEng (Release Engineering) project. It contains:
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.
Build Scripts and Map Files
The build scripts and map files are used to drive the automatic build and tagging process on Hudson. A cron script checks Git repositories regularly for updates. If new commits are found, a repository is tagged, the map file is updated with the new tag and a Hudson build will be started. PDE Build uses the map files to calculate a bundle qualifier.
Local Build Process from Eclipse
It is possible to setup the headless build process (see below) locally. However, a more straightforward approach is 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.
Headless Build Process
The build process is entirely based on PDE Build (which is based on Ant). The main build script includes targets for calling from a plain Ant as well as from an Eclipse Ant. The plain Ant target bootstraps a PDE Builder from Eclipse CVS and then launches the Eclipse target using Eclipse Ant. There is also a shared external tool launch configuration that can be used for building from within Eclipse.
The build process if as follows:
- Bootstrap PDE Builder
- Build target platform from target definition (using p2 mirror functionality)
- Fetch sources using map files
- Build org.eclipse.gyrex.features.master
- Assemble Gyrex Server Product
- Produce final p2 Repo (including signing of artifacts when executed on Eclipse.org infrastructure)
- Publish to download.eclipse.org (when executed on Eclipse.org infrastructure)
In order to use the headless build locally, you need to clone the Gyrex Releng repository. You also need to have a working Ant, Git and CVS executable on your system and in your path (so that the build can invoke it). The build script to invoke is
org.eclipse.gyrex.releng/builder/build.xml. Please also create a local
build.local.properties before in order to set some important, required paths.
As part of the build process the Ant scripts bootstrap PDE Builder from Eclipse CVS repos. It then launches the PDE Builder with the same build script but this time calls the Ant target
runInEclipse. Of course, this target can also be called directly from a running Eclipse. However, you must have Eclipse PDE, CVS as well as the Git Fetch Factory for PDE installed in your running Eclipse. The Git Fetch Factory can be installed from http://download.eclipse.org/egit/pde/updates-nightly/.
Hudson Build Jobs
The nightly job is used for CI compile check builds. It monitors the full source tree for changes and kicks of a build every once in a while when somebody checked something into source control. However, it always uses HEAD when performing checkouts. The build results should not be used.
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).