README.adoc

Spring Roo

Thanks for checking out Spring Roo from Git.

These instructions are aimed at experienced developers looking to develop Spring Roo itself. If you are new to Spring Roo or would simply like to try a release that has already been built, tested and distributed by the core development team, we recommend that you visit the Spring Roo Home Page and download an official release.

One-time setup instructions

We’ll assume you typed the following to checkout Roo (if not, adjust the paths in the following instructions accordingly):

cd~
git clone git@github.com:spring-projects/spring-roo.git

In the instructions below, $ROO_HOME refers to the location where you checked out Roo (in this case it would be ROO_HOME="~/roo"). You do NOT need to add a $ROO_HOME variable. It is simply used in these docs.

Next double-check you meet the installation requirements:

A proper installation of Java 7

Maven 3.0.1+ properly installed and working with your Java version

Internet access so that Maven can download required dependencies

A Git command line client installed (required by Roo’s Maven build for inserting the current revision number into OSGi bundle manifests)

Next you need to setup an environment variable called MAVEN_OPTS. If you already have a MAVEN_OPTS, just check it has the memory sizes shown below (or greater).

If you’re following our checkout instructions above and are on a *nix machine, you can just type:

Next you need to publish your key to a public keyserver. Take a note of the "sec" key ID shown from the --list-secret-keys. In my case it’s key ID "00B5050F".

Push your public key to a keyserver via the command "gpg --keyserver hkp://pgp.mit.edu --send-keys 00B5050F" (of course changing the key ID at the end). Most public key servers share keys, so you don’t need to send your public key to multiple key servers.

Finally, every time you build you will be prompted for the password of your
key.

You have several options:

Type the password in every time

Include a -Dgpg.passphrase=thephrase argument when calling "mvn"

Edit ~/.bashrc and add -Dgpg.passphrase=thephrase to MAVEN_OPTS

Edit your active Maven profile to include a "gpg.passphrase" property:

Of course the most secure option is to type the password every time. However, if you’re doing a lot of builds you might prefer automation.

Note

if you’re new to GPG: don’t lose your private key! Backup the secring.gpg file, as you’ll need it to ever revoke your key or sign a replacement key (the public key servers offer no way to revoke a key unless you can sign the revocation request).

Developing within eclipse

Spring Roo itself does not use AspectJ and therefore any standard IDE can be used for development. No extra plugins are needed and the team use "mvn clean eclipse:clean eclipse:eclipse" to produce Eclipse project files that can be imported via File > Import > Existing Projects into Workspace.

In theory you could use the m2eclipse plugin. The Roo team just tends to use eclipse:clean eclipse:eclipse instead.

Running the command line tool

Roo uses OSGi and OSGi requires compiled JARs. Therefore as you make changes in Roo, you’d normally need to "mvn package" the relevant project(s), then copy the resulting JAR files to the OSGi container.

To simplify development and OSGi-related procedures, Roo’s Maven POMs have been carefully configured to emit manifests, SCR descriptors and dependencies.

These are mostly emitted when you use "mvn package".

To try Roo out, you should type the following:

cd$ROO_HOME
mvn install
cd~/some-directory
roo-dev

It’s important that you run roo-dev from a directory that you’d like to eventually contain a Roo-created project.

Important

Don’t try to run roo-dev from your $ROO_HOME directory.

If this fails, please review the "OSGi Wrapping JARs" section above.

Notice we used "mvn install" rather than "mvn package". This is simply for convenience, as it will allow you to "cd" into any Roo module subdirectory and "mvn install". This saves considerable build time if changes are only being made in a single module.

Roo ships with a command line tool called "roo-dev". This is also a Windows equivalent. It copies all relevant JARs from the Roo directories into ~/roo/bootstrap/target/osgi. This directory represents a configured Roo OSGi instance.

"roo-dev" also launches the OSGi container, which is currently Apache Felix. It also activate "development mode", which gives fuller exceptions, more file activity reporting, extra flash messages related to OSGi events etc.

STS integration

If you wan to include Roo Support on your STS, follow the next instructions:

Open your STS IDE

Open STS dashboard and search Spring Roo

Install Spring IDE - Roo Extension

Install Spring IDE - Roo Extension

Restarts STS IDE

With that simple steps you will include Roo Support on your STS IDE.

Git Polices

When checking into Git, you must provide a commit message which begins with the relevant Roo Jira issue tracking number. The message should be in the form "ROO-xxx: Title of the Jira Issue". For example:

ROO-1234: Name of the task as stated in Jira

You are free to place whatever text you like after this prefix. The prefix ensures FishEye is able to correlate the commit with Jira. eg:

ROO-1234: Name of the task as stated in Jira - add extra file

You should not commit any IDE or Maven-generated files into Git.

Try to avoid "git pull", as it creates lots of commit messages like "Merge branch master of git.springsource.org:roo/roo". You can avoid this with "git pull --rebase".

Let’s take the simple case where you just want to make a minor change against master. You don’t want a new branch etc, and you only want a single commit to eventually show up in "git log". The easiest way is to start your editing session with this:

git pull

That will give you the latest code. Go and edit files. Determine the changes with:

git status

You can use "git add -A" if you just want to add everything you see.

Next you need to make a commit. Do this via:

git commit -e

The -e will cause an editor to load, allowing you to edit the message. Every commit message should reflect the "Git Policies" above.

Now if nobody else has made any changes since your original "git pull", you can simply type this:

git push origin

If the result is [ok], you’re done.

If the result is [rejected], someone else beat you to it. The simplest way to workaround this is:

git pull --rebase

The --rebase option will essentially do a git pull, but then it will reapply your commits again as if they happened after the git pull. This avoids verbose logs like "Merge branch master".

Releasing

Roo is released on a regular basis by the Roo project team. To perform releases and make the associated announcements you require appropriate permissions to many systems (as listed below). As such these notes are intended to assist developers with such permissions complete releases.

Our release procedure may seem long, but that’s because it includes many steps related to final testing and staging releases with other teams.

Build the reference guide and deploy to the static staging server. You must be connected to the VPN for deployment to work. Note that http://projects.spring.io/spring-roo/ is updated bi-hourly from staging:

cd$ROO_HOME/deployment-support
mvn clean site site:deploy

Create the final assembly ZIP (must happen after site built). We run full tests here, even ensuring all the Maven artifacts used by user projects are available. This takes a lot of time, but it is very helpful for our users:

Repeat the verification tests on the assembly ZIP (see above). See note below if coordinating a release with the STS team.

Typically after this step you’ll send the tested assembly ZIP to the STS team for a concurrent release. Allow time for them to test the ZIP before starting step 8. This allows verification of STS embeddeding. Keep your ROO_HOME intact during this time, as you need the **/target and /.git directories for steps 8 and 9 to be completed.

If the verifications pass, push the Git tag up to the server:

cd$ROO_HOME
git push --tags

Deploy the JARs to Maven Central

cd$ROO_HOME
mvn clean deploy

Deploy assembly ZIP (binaries) to the production download servers (it takes up to an hour for these to be made fully downloadable):

If any problems are detected before step 8, simply fix, push and start from step 1 again. You have not deployed anything substantial (ie only the reference guide) until step 8, so some corrections and re-tagging can be performed without any difficulty. The critical requirement is to defer step 8 (and beyond) until you’re sure everything is fine.