Skip to content

Latest commit

 

History

History
205 lines (151 loc) · 8.19 KB

CONTRIBUTING.adoc

File metadata and controls

205 lines (151 loc) · 8.19 KB
Raw

Contributing to Spring Roo

Thanks for contributing Spring Roo.

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.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Before Contributing

Search StackOverflow first; discuss if necessary

For general usage questions please ask on stackoverflow, tagged with spring-roo.

Search JIRA; create an issue if necessary

Is there already an issue that addresses your concern? Do a bit of searching in the Spring ROO issue tracker to see if you can find something similar. If you do not find something similar, please create a new JIRA issue before submitting a pull request unless the change is truly trivial.

Sign the Contributor License Agreement (CLA)

If you have not previously done so, please sign the Contributor License Agreement.

GPG (PGP) Setup

Roo uses GPG to automatically sign build outputs. If you haven’t installed GPG, download and install it:

Ensure you have a valid signature. Use "gpg --list-secret-keys".

You should see some output like this:

$ gpg --list-secret-keys
/home/balex/.gnupg/secring.gpg
sec   1024D/00B5050F 2009-03-28
uid                  Ben Alex <[email protected]>
uid                  Ben Alex <[email protected]>
uid                  Ben Alex <[email protected]>
ssb   4096g/2DB6833B 2009-03-28

If you don’t see the output, it means you first need to create a key.

It’s very easy to do this, just use "gpg --gen-key".

Then verify your newly-created key was indeed created: "gpg --list-secret-keys".

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"

    $ ./mvnw clean install -Dgpg.passphrase=thephrase

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

  • Edit your active Maven profile to include a "gpg.passphrase" property with readle value:

    <profiles>
  <profile>
    <properties>
      <gpg.passphrase>roorules</gpg.passphrase>

  • Use an encrypted "gpg.passphrase":

    1. Create a master password

      $ ./mvnw --encrypt-master-password <password>

    2. Store this password in the ~/.m2/settings-security.xml. It should look like:

      <settingsSecurity>
  <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity>

    3. Encrypt gpg passphrase:

      $ ./mvnw --encrypt-password <passphrase>

    4. Store it into your settings.xml file in the server section. This will look like:

      <settings>
...
  <servers>
  ...
    <server>
      <id>gpg.passphrase</id>
      <passphrase>{COQLCE6DU6GtcS5P=}</passphrase>
    </server>
  ...
  </servers>
...
</settings>

Of course the most secure options are to type the password every time and to encrypt the password. However, the most comfortable is to encrypt the password especially if you’re doing a lot of builds.

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).

Create a Fork

For contributors that want to write code, we encourage contributions through pull requests from forks of this repository.

Note
 Developers with appropriate permissions may work through branches.

The commit messages must follow these conventions, if you are fixing an existing issue add "ROO-XXXX:" (without the quotation marks) at the begining of the commit message (where XXXX is the issue number).

Code Conventions

  • Use the Spring Roo project code format conventions.

  • Make sure all new .java files to have the Javadoc class comment with the @author tag identifying you as well as a paragraph on what the class is for.

  • Add the ASF license header comment to all new .java files (copy from existing files in the project).

  • Add the Javadoc comments to all new class methods as well as class attributes.

Working with the Code

Spring Roo itself is a standard Maven project and therefore any standard IDE can be used for development. No extra plugins are needed.

The team use Eclipse or STS to develop Roo, just import the project branch as standard Maven project via File › Import › Maven › Existing Maven Projects into the Workspace.

In theory you could use the m2eclipse plugin. The Roo team just tends to use the shell command ./mvnw instead.

Building from Source

The project can be built from the root directory using the standard maven command:

$ ./mvnw clean install
Note
 You may need to increase the amount of memory available to Maven by setting a MAVEN_OPTS environment variable with the value -Xmx1024m -XX:MaxPermSize=512m

If you are rebuilding often, you might also want to skip the housekeeping until you are ready to submit a pull request:

$ ./mvnw clean install -DskipTests -Dmaven.gpg.skip=true -Dgpg.skip=true -Dmaven.javadoc.skip=true -Dformatter.skip=true -Dmaven.source.skip=true -Dmaven.formatter.skip=true -DskipRelease

Test the build

Roo ships with a command line tool called roo-dev. It copies all relevant JARs from a success build into $ROO_HOME/runtime/bootstrap/target/osgi/. This directory represents a Roo build snapshot instance.

To test your contribution just try Roo, go to the application project directory and run roo-dev:

$ cd $PROJECT_HOME
$ $ROO_HOME/runtime/bootstrap/roo-dev