Chapter 17. Development Processes

In this chapter we'll cover how we develop Roo, and how you can check it out and get involved.

17.1. Guidelines We Follow

Whether you are part of the Roo core development team, you want to contribute patches, or you want to develop add-ons there are a few guidelines we would like to bring to your attention.

  1. Design Goals

    • High productivity for Java developers

      • Encourage reuse of existing knowledge, skills and experience

    • Eliminate barriers to adoption, no runtime component, minimal size, best possible development experience

      • Avoid lock-in

      • No runtime component

      • Minimal download size

      • Best possible development experience

    • Embrace the strengths of Java

      • Development-time: tooling, popularity, API quality, static typing

      • Deploy-time: performance, memory use, footprint

  2. Embrace the advantages of AspectJ

    • Use AspectJ inter-type declarations (ITDs) for “active” generation

      • Active generation automatically maintains output

    • Delivers compilation unit separation of concerns

      • Easier for users, and easier for us as developers

    • Instant IDE support

      • Reduce time to market and adoption barriers

    • Other good reasons

      • Mature, “push in” refactor, compile-time is welcome

  3. ITD Model

    • Roo owns *_Roo_*.aj files

      • Will delete them if necessary

    • Every ITD-providing add-on registers a 'suffix' (namespace)

      • E.g. the 'Entity' add-on provides *_ROO_JPA_ACTIVE_RECORD.aj

      • A missing ITD provider causes AJ file removal

    • ITDs have proper import management

      • So they look and feel normal to developers

      • So they 'push-in refactor' in a natural form

  4. Usability = Highest Priority

    • Interactivity of Roo Shell

    • Tab completion, context awareness, command hiding, hint support, etc

    • Background monitoring of externally made changes (allows integration with any development style)

    • Background monitoring to avoid crude 'generation' steps

  5. Immutability of Metadata Types

    • Immutability as a first step to manage concurrency

    • String-based keys (start with 'MID:')

    • Metadata and keys built on demand only (never persisted)

    • Metadata can depend on other metadata

      • if 'upstream' metadata changes, 'downstream' metadata is notified

      • Some metadata will want to monitor the file system

    • Central metadata service available and cache is provided to enhance performance

  6. Conventions we follow

    • Ensure usability is first-class

    • Minimize the JAR footprint that Roo requires

    • Relocate runtime needs to sister Spring projects

    • Embrace immutability as much as possible

    • Maximize performance in generated code

    • Minimize memory consumption in generated code

    • Use long artifact IDs to facilitate identification

    • Don't put into @Roo* what you could calculate

    • Don't violate generator predictability conventions

17.2. Source Repository

We develop against a public Git repository from which you can anonymously checkout the code:

git clone git://git.springsource.org/roo/roo.git spring-roo

Review source code without Git http://git.springsource.org/roo/roo/trees/master or https://fisheye.springsource.org/changelog/spring-roo.

Roo itself uses Maven, so it's very easy to build the standard package, install, assembly and site goals. PGP should be installed, see the 'Setting Up for Development' section below for details.

17.3. Setting Up for Development

We maintain up-to-date documentation in the readme.txt in the root of the checkout location. Please follow these instructions carefully.

17.4. Submitting Patches

Submitting a patch for a bug, improvement or even a new feature which you always wanted addressed can be of great help to the Spring Roo project.

To get started, you could build Roo from sources (as described above), and locally start changing source code as you see fit. Then test your changes and if all works well, you can create a git patch and attach it to a ticket in our bug tracker. To create a patch with Git you can simply use the following command in Roo's source code root directory:

<spring-roo>$ git status
<spring-roo>$ git add (files)
<spring-roo>$ git commit -m 'Explain what I changed'
<spring-roo>$ git format-patch origin/master --stdout > ROO-XXXX.patch

The resulting .patch file can then be attached to the ROO-XXXX ticket in our bug tracker.

17.5. Path to Committer Status

Essentially if you submit a patch and we think it is useful to commit to the code base, we will ask you to complete our contributor agreement. This is just a simple web form that deals with issues like patents and copyrights. Once this is done, we can apply your patch to the source code repository.

If you're working on a large module that is part of the Roo Git repository, and you have a history of providing quality patches and "looking after" the code you've previously written, we will likely invite you to join us as a committer. We have certain commit policies which are more fully detailed in the readme.txt that is in the root of the checkout location. We have numerous committers external to VMware, so Roo is very much a welcoming project in terms of committers. We look forward to you joining us.