Last updated by 5 years ago

Page: Developer Guidelines, Version:8


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.

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 of Grails copy with:
    • svn co @
  • Update the Grails version number in the following files:
    • README
    • bin/startGrails
    • bin/startGrails.bat
    • src/grails/grails-macros.xml
    • test/commons/grails/util/
  • Make sure the dependencies are correctly documented in dependencies.txt
  • Checkin and confirm that the continuous integration tests pass
  • Tag the release by doing:
    • svn cp
  • Build the distribution by running "ant"
  • Upload the distribution to
  • Upload to the appropriate Maven repository (1.1 and above):
    • ant maven-deploy
  • Checkout a copy of Grails docs with:
    • svn co
  • Tag the doc version with:
    • svn cp
  • Build the docs with by running "ant"
  • Upload the doc distribution to
  • Edit the download page at
  • Announce the release.

Maven configuration

In order to deploy the Grails artifacts to the Codehaus repositories, you will have to do some setup - see the Codehaus Maven repository instructions for the full details. Most of the work has already been done, but to perform the actual upload, you will need to add the following to your Maven settings (usually ~/.m2/settings.xml ):


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.


Because Maven caches the files it downloads, you have to be careful when testing that you aren't picking up artifacts from previous runs/builds. Before publishing a release, you must always try the Maven integration out with a clean cache. To do that, just follow these steps:

  1. Remove everything under ~/.m2/repository/ .
  2. Install latest version of grails-maven-archetype by running mvn install from your working copy.
  3. Install latest version of grails-maven-archetype by running mvn install from your working copy.
  4. Install latest version of grails-maven-plugin by running mvn install .
  5. Install latest version of Grails by running ant maven-install .
You can then test the Maven integration, although make sure that you are using the correct versions in your project POMs and when creating a project from the archetype. See Maven Integration for more info.

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.

Keeping branches in sync. with trunk

Here is the process that you should follow when keeping a branch synchronised with trunk. The version of subversion we use does not support merge-tracking, so the merged versions must be tracked in log messages.

  1. In a branch working copy (e.g. GRAILS_1_1), do "svn log | fgrep --context=3 'Merged revisions' ". Basically, you want to find the last merge.
  2. Make a note of the second ("end" below) revision in the message of the most recent merge commit. The message looks like this:
    "Merged revisions <start>:<end> from trunk to branch <branch label>."
    If this is the first merge to the branch, the "end" revision is the revision immediately before the branch was created.
  3. Now perform the merge:
    svn merge -r <end>:<latest trunk rev> .
    , where <end> is the revision noted from the previous step, and <latest trunk rev> is the most recent revision on trunk. Actually you can select any revision you want really, as long as it is on trunk and it comes after <end>.
  4. Fix any conflicts.
  5. Commit the changes with the message: "Merged revisions <end>:<latest trunk rev> from trunk to branch <branch label>."
That's it. One final thing: to keep the merges as smooth as possible, please do not commit the same change to both trunk and the branch. If you want the change on both immediately, commit the change to trunk and then perform the merge.