Contributing to Gradle
Thank you for considering making a contribution to Gradle! This guide explains how to setup your environment for Gradle development, how to identify tasks to work on, and where to get help if you encounter trouble.
In order to make changes to Gradle, you'll need:
- A text editor or IDE. We use and recommend IntelliJ IDEA CE.
- A Java Development Kit (JDK) version 1.7 or higher
- git and a GitHub account
Gradle uses a pull request model for contributions. Fork gradle/gradle and clone your fork. Configure your Git username and email with
git config user.name 'First Last' git config user.email firstname.lastname@example.org
You can generate the IntelliJ project by running
./gradlew idea # *nix-based systems gradlew idea # Windows
then "Open" it with IntelliJ.
You can generate the Eclipse projects by running
./gradlew eclipse # *nix-based systems gradlew eclipse # Windows
Running or debugging gradle under Eclipse
- Create a
Java Application Run/Debug configuration as
- Right click on
Run as->Run configuration
- In the Arguments tab, enter:
- In the Working Directory tab:
enter you project's root directory
- Apply/Run/Close as needed
If you'd like to contribute to Gradle but aren't sure where, please look for issues labelled help-wanted. We have designated these issues as good candidates for easy contribution.
Larger Changes (features or enhancements)
Before starting to work on a feature or a fix, please open a discussion about your proposed changes on the Gradle Developer List. Doing so helps to ensure that:
- You understand how your proposed changes fit with the strategic goals of the Gradle project.
- You can get early feedback on your proposed changes, and suggestions as to the best approach to implementation.
- We can all collaborate in creating a design document. This is required for all changes that affect behavior or public API.
Code Change Guidelines
All code contributions should contain the following:
- Unit Tests (using Spock) for any logic introduced
- Integration Test coverage of the bug/feature at the level of build execution. Please annotate tests guarding against a specific GitHub issue
- Documentation in the User Guide and DSL Reference (under
subprojects/docs/src/docs). You can generate docs by running
@authortags and committer names are not used in the codebase (contributions are recognised in the commit history and release notes)
If you're not sure where to start, ask on the developer list. There's likely a number of existing examples to help get you going.
Try to ensure that your code & tests will run successfully on Java 6, and on both *nix and Windows platforms. The Gradle CI will verify this, but it helps if things work first time.
- Avoid using features introduced in Java 1.7 or later
- Be careful to normalise file paths in tests. The
org.gradle.util.TextUtilclass has some useful utility functions for this purpose.
After making changes, you can test them in 2 ways:
To run tests, execute
./gradlew :<subproject>:check where
<subproject> is the name of the sub-project that has changed. For example:
To try out a change in behavior manually, install Gradle source locally and use it
./gradlew install -Pgradle_installPath=/any/path /any/path/bin/gradle taskName
You can debug Gradle by adding
-Dorg.gradle.debug=true when executing. Gradle will wait for you to attach at debugger at
localhost:5005 by default. We recommend disabling the Gradle Daemon when debugging (
Creating Commits And Writing Commit Messages
The commit messages that accompany your code changes are an important piece of documentation, and help make your contribution easier to review. Please consider reading How to Write a Git Commit Message. Minimally, follow these guidelines when writing commit messages.
- Keep commits discrete: avoid including multiple unrelated changes in a single commit
- Keep commits self-contained: avoid spreading a single change across multiple commits. A single commit should make sense in isolation
- If your commit pertains to a GitHub issue, include (
Issue: #123) in the commit message on a separate line
- Please check that your email address matches that on your CLA
Submitting Your Change
Before we can accept any code contributions, you must complete and electronically sign a Gradle CLA.
Once received, the pull request will be reviewed by a Gradle core developer. Your pull request will be given higher priority if you:
- Have first discussed the change on the Gradle Developer list.
- Have followed all of the Contribution Guidelines here.
After review, and usually after a number of iterations of development, your pull request may be merged into the Gradle distribution.
We deeply appreciate your effort toward improving Gradle. For any contribution, large or small, you will be immortalized in the release notes for the version you've contributed to.
If you enjoyed this process, perhaps you should consider getting paid to develop Gradle?