Last updated by 1 year ago

Page: Developer Guidelines, Version:37

Overview

If you're looking for documentation about the Grails source code see the Developer Documentation, this page serves as a guideline to the processes for committers working on Grails. As Grails takes on more developers it is important that a process is followed so that that Grails maintains a high level of quality. This section details that process.

Git and Grails

We are starting to move to Git for our SCM needs. If you are unfamiliar with the tool, we recommend you check out these guides:

To start playing with the latest Grails source code, just clone the Grails repository on GitHub: 
git clone git://github.com/grails/grails-core.git

Git Settings

Make sure you configure Git appropriately with the same email that you registered with on github:

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL"

You can verify these are configured appropriately by running:

git config --list

Git and IDE Support

Currently IntelliJ IDEA 8.1 provides good Git support.

Git on Windows

The best two options for Windows at the moment are:

  • the dedicated msysgit installer (see the featured downloads for the latest *.exe installer)
  • your IDE!
You can find out more about installation and usage in the Illustrated Guide to Git on Windows.

Git on Mac OS X

If you're on Mac OS X there are a number of useful tools you may want to use to take advantage of Git:

To make TextMate the default commit message editor you can do so by running the following command:

git config --global core.editor "mate -w"

Grails and Gradle

As of January 2010 Grails has a new Gradle based build. Gradle is a build system for Groovy/Java projects that uses Groovy to define Gradle build scripts.

The build.gradle file in the root of the Grails project controls the build and pulls in various other scripts that define tasks from the GRAILS_HOME/gradle directory. Here are some useful commands:

$ ./gradlew assemble // build the Grails distribution
$ ./gradlew libs // build the Grails jar files
$ ./gradlew test // run the tests

To run a single test you can use the -Dtest.single= prefix followed by the test name:

$ ./gradlew -Dtest.single=MappingDsl grails-test-suite-persistence:test

The above command will run a test case called MappingDslTests in the Grails codebase.

The Change Approval Process

Clearly not every great idea should be added directly to Grails, as a committer you have a responsibility to inform others of new ideas before touching the codebase. The following process should be followed as a general rule:

  • Send an email to the developer list with proposals of the change/new feature
  • If the change is agreed (and ultimately the final decision is down to the Grails project lead Graeme) add a new JIRA issue.
  • When committing the changes refer to the JIRA issue number in the commit comments, e.g. GRAILS-001
  • Make sure you only do minor commits without approval

The Release Process

When doing a Grails release please follow these steps:

  • Release the version in JIRA
  • Checkout a clean copy of Grails with:
    • git clone git@github.com:grails/grails.git
  • Update the Grails version number in the following files:
    • build.gradle
    • build.properties
    • bin/startGrails
    • bin/startGrails.bat
    • src/test/grails/util/GrailsUtilTests.java
  • Make sure the dependencies are correctly documented in dependencies.txt
  • Checkin and confirm that all of the continuous integration tests pass (grails_core and grails_functional_tests)
  • Tag the release by doing:
    • git tag TAGNAME
    • git push --tags
Tag names should look like v1.2, v1.3, v1.4M1, v1.4RC1 etc…
  • Build the distribution by running "./gradlew assemble"
  • Test the distribution (including testing creating a project with STS)
  • Upload all of the zip/jar files in the "build/distributions" directory to https://dav.codehaus.org/dist/grails/
  • Upload to the appropriate Maven repository (1.1 and above):
    • ./gradlew uploadPublished
  • Edit the download page at http://grails.org/Download
  • Announce the release.

Testing and Continuous Integration

Testing is seen as crucial to the success of the project and Grails aims for maximum coverage. Before even thinking of committing anything make sure you have implemented sufficient unit tests to cover the code.

It doesn't matter how complicated your unit tests become (and they're often more complicated than the code itself with Grails) they must exist and they must cover as much as possible.

Before committing to Grails make sure you run the entire test suite against Grails and only commit once the test suite is passing.

Directly following your commit, monitor the continuous integration build server and ensure the build completes successfully. A broken build must be immediately corrected.

Maven

See the Maven integration page in the developer docs for information on developing and releasing the Grails Maven integration.

Notes on current state of coverage

At the moment not every aspect of Grails is covered by a unit test. This will be corrected over time, but these guidelines are in place so the situation doesn't degrade as we are still in a position to be able to ensure Grails has a solid foundation for the future.