How to contribute a patch to Gradle

Intro

This page describes the steps you should take to contribute a patch to Gradle. The process is pretty much the same for feature enhancements, bug fixes and documentation contributions.

Gradle Master Repository

Our master repository is a Git repository hosted at GitHub: http://github.com/gradle/gradle/tree/master

We use Git repositories and GitHub because it allows us to easily review commits from forked repositories and finally commit them to our master repository.

Sharing your work

Ways to share your work

• Create a Git fork of the Git Gradle master repository.

General - getting setup

1. Create a Jira issue for the change, if one does not already exist.

Git - getting setup

1. Create a GitHub account.
   - set the account up with a SSH key so you can commit your changes
   - execute the global Git configuration, check your account page for the details
2. Fork one of Gradle developer repositories that is already available on GitHub.
3. Checkout your forked repository.

General - getting your contribution ready

1. Write some unit tests to demonstrate the bug and that your changes do what they are supposed to do. For Gradle, we are using JUnit 4.7 and JMock 2.5 to write unit tests. You might also add an integration test, or change an existing integration test.
2. Make sure your new tests and all the existing tests pass, by executing the developerBuild task for the Gradle build. For example, by running ./gradlew developerBuild.
   1. The integration tests do take a while to execute, depending on your machine they might take 15-30 minutes to run.
   2. You should note that currently the developerBuild task is broken on windows (see http://jira.codehaus.org/browse/GRADLE-764, which also provides a work around).
3. Once you are happy with your changes, update the Jira to inform us that your changes are ready for review. Please make sure that your applies cleanly to the latest version of the repository of your choice. We will review / test your changes and apply them when they are ready.

Some notes

1. Gradle targets Java 1.5. It is fine to use Java 1.5 language features and APIs. Do not use APIs from later java versions.
2. The core of Gradle is implemented in java. The rest can be implemented in groovy. You can write unit tests in either java or groovy, as you choose.
3. You might find it useful to know how to build Gradle from source.

Working with Git to contribute

First you need to get a copy of the Git repository:

Next you will most likely want to create a feature branch to develop your change on

Switch to the new branch

Develop your change, commit and push your changes to GitHub (as often as possible so you don't loose any of your work).

commit command (please provide usefull commit messages)

push command

Reviewing changes

GitHub makes reviewing contributions really easy. Changes that are made on forks of the parent repository are available for review in the "Fork Queue" tab.

1. Specify the branch you want to apply changes on (or create a new branch to hold the commits of the contribution). 
2. Review the commits that you want to apply on the branch
3. Select the commits that you want to apply and commit them
4. Pull the changes to your local Git repo and test/ review it some more
5. When ready merge it into the master branch.