(Quick Reference)

16 Contributing to Griffon - Reference Documentation

Authors: Andres Almiray

Version: 1.2.0

16 Contributing to Griffon

Griffon is an open source project with an active community and we rely heavily on that community to help make Griffon better. As such, there are various ways in which people can contribute to Griffon. One of these is by writing useful plugins and making them publicly available. In this chapter, we'll look at some of the other options.

16.1 Report Issues in JIRA

Griffon uses JIRA to track issues in the core framework, its documentation, its website, and many of the public plugins. If you've found a bug or wish to see a particular feature added, this is the place to start. You'll need to create a (free) JIRA account in order to either submit an issue or comment on an existing one.

When submitting issues, please provide as much information as possible and in the case of bugs, make sure you explain which versions of Griffon and various plugins you are using. Also, an issue is much more likely to be dealt with if you attach a reproducible sample application.

Reviewing issues

There are quite a few old issues in JIRA, some of which may no longer be valid. The core team can't track down these alone, so a very simple contribution that you can make is to verify one or two issues occasionally.

Which issues need verification? A shared JIRA filter will display all issues that haven't been resolved. Just pick one or two of them and check whether they are still relevant.

Once you've verified an issue, simply edit it by adding a "Last Reviewed" comment. If you think the issue can be closed, then also add a "Flagged" comment and a short explanation why.

16.2 Build From Source and Run Tests

If you're interested in contributing fixes and features to the core framework, you will have to learn how to get hold of the project's source, build it and test it with your own applications. Before you start, make sure you have:
  • A JDK (1.6 or above)
  • A git client

Once you have all the pre-requisite packages installed, the next step is to download the Griffon source code, which is hosted at GitHub in several repositories owned by the "griffon" GitHub user. This is a simple case of cloning the repository you're interested in. For example, to get the core framework run:

git clone http://github.com/griffon/griffon.git

This will create a "griffon" directory in your current working directory containing all the project source files. The next step is to get a Griffon installation from the source.

Creating a Griffon installation

If you look at the project structure, you'll see that it doesn't look much like a standard GRIFFON_HOME installation. But, it's very simple to turn it into one. Just run this from the root directory of the project:

./gradlew installBinary

However before you do so make sure you configure GRIFFON_HOME pointing to a directory where the binaries will be placed. Once the above command has finished. When you next type run the griffon command, you'll be using the version you just built.

This will fetch all the standard dependencies required by Griffon and then build a GRIFFON_HOME installation. Note that this target skips the extensive collection of Griffon test classes, which can take some time to complete.

Running the test suite

All you have to do to run the full suite of tests is:

./gradlew test

These will take a while, so consider running individual tests using the command line. For example, to run the test case MappingDslTests simply execute the following command:

./gradlew -Dtest.single=EnvironmentTests :griffon-rt:test

Note that you need to specify the sub-project that the test case resides in, because the top-level "test" target won't work....

Developing in IntelliJ IDEA

You need to run the following gradle task:

./gradlew idea

Then open the project file which is generated in IDEA. Simple!

16.3 Submit Patches to Griffon Core

If you want to submit patches to the project, you simply need to fork the repository on GitHub rather than clone it directly. Then you will commit your changes to your fork and send a pull request for a core team member to review.

Forking and Pull Requests

One of the benefits of GitHub is the way that you can easily contribute to a project by forking the repository and sending pull requests with your changes.

What follows are some guidelines to help ensure that your pull requests are speedily dealt with and provide the information we need. They will also make your life easier!

Create a local branch for your changes

Your life will be greatly simplified if you create a local branch to make your changes on. For example, as soon as you fork a repository and clone the fork locally, execute

git checkout -b mine

This will create a new local branch called "mine" based off the "master" branch. Of course, you can name the branch whatever you like - you don't have to use "mine".

Create JIRAs for non-trivial changes

For any non-trivial changes, raise a JIRA issue if one doesn't already exist. That helps us keep track of what changes go into each new version of Griffon.

Include JIRA issue ID in commit messages

This may not seem particularly important, but having a JIRA issue ID in a commit message means that we can find out at a later date why a change was made. Include the ID in any and all commits that relate to that issue. If a commit isn't related to an issue, then there's no need to include an issue ID.

Make sure your fork is up to date

Since the core developers must merge your commits into the main repository, it makes life much easier if your fork on GitHub is up to date before you send a pull request.

Let's say you have the main repository set up as a remote called "upstream" and you want to submit a pull request. Also, all your changes are currently on the local "mine" branch but not on "master". The first step involves pulling any changes from the main repository that have been added since you last fetched and merged:

git checkout master
git pull upstream

This should complete without any problems or conflicts. Next, rebase your local branch against the now up-to-date master:

git checkout mine
git rebase master

What this does is rearrange the commits such that all of your changes come after the most recent one in master. Think adding some cards to the top of a deck rather than shuffling them into the pack.

You'll now be able to do a clean merge from your local branch to master:

git checkout master
git merge mine

Finally, you must push your changes to your remote repository on GitHub, otherwise the core developers won't be able to pick them up:

git push

You're now ready to send the pull request from the GitHub user interface.

Say what your pull request is for

A pull request can contain any number of commits and it may be related to any number of issues. In the pull request message, please specify the IDs of all issues that the request relates to. Also give a brief description of the work you have done, such as: "I refactored the resources injector and added support for custom number editors (GRIFFON-xxxx)".