Thank you for considering a contribution to Gradle! This guide explains how to:
Before starting to work on a feature or a fix, please open an issue to discuss the use case or bug with us. This can save both you and us a lot of time. For any non-trivial change, we'll ask you to create a short design document explaining:
This can be done directly inside the GitHub issue or (for large changes) you can share a Google Doc with us.
Please do not report security issues to the public issue tracker. Please send security issues to security@gradle.com.
In order for your contributions to be accepted, you must sign off your Git commits to indicate that you agree to the terms of Developer Certificate of Origin.
In order to foster a more inclusive community, Gradle has adopted the Contributor Covenant.
Contributors must follow the Code of Conduct outlined at https://gradle.org/conduct/.
To create an install from the source tree you can run either of the following:
./gradlew install -Pgradle_installPath=/usr/local/gradle-source-build
This will create a minimal installation; just what's needed to run Gradle (i.e. no sources nor docs).
You can then build a Gradle based project with this installation:
/usr/local/gradle-source-build/bin/gradle «some task»
To create a full installation (includes sources and docs):
./gradlew installAll -Pgradle_installPath=/usr/local/gradle-source-build
To create a Gradle distribution from the source tree you can run either of the following:
./gradlew :distributions-full:binDistributionZip
This will create a minimal distribution at subprojects/distributions-full/build/distributions/gradle-<version>-bin.zip
, just what's needed to run Gradle (i.e. no sources nor docs).
You can then use it as a Gradle Wrapper local distribution in a Gradle based project by using a file:/
URL pointing to the built distribution:
./gradle wrapper --gradle-distribution-url=file:/path/to/gradle-<version>-bin.zip
To create a full distribution (includes sources and docs):
./gradlew :distributions-full:allDistributionZip
The full distribution will be created at subprojects/distributions-full/build/distributions/gradle-<version>-all.zip
. You can then use it as a Gradle Wrapper local distribution:
./gradle wrapper --gradle-distribution-url=file:/path/to/gradle-<version>-all.zip
In order to make changes to Gradle, you'll need:
Gradle uses pull requests 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 user@example.com
You require IntelliJ 2018.3.1 or newer.
build.gradle.kts
file with IntelliJ and choose “Open as Project”.idea
folderNOTE: Due to the project size, the initial import can take a while and IntelliJ might become unresponsive for several seconds during this period.
IntelliJ automatically hides stacktrace elements from the org.gradle
package, which makes running/debugging tests more difficult. You can disable this behavior by changing IntelliJ Preferences under Editor -> General -> Console. In the “Fold lines that contain” section, remove the org.gradle
entry.
The build leverages the built-in Java Toolchain support to compile and execute tests. Available JDKs on your machine are automatically detected and wired for the various compile and test tasks.
If you want to explicitly run tests with a different Java version: Specify either a Gradle or System property testJavaVersion
with the major version of the JDK you want the tests to run with (e.g. -PtestJavaVersion=14
).
If some JDKs on your machine are not automatically detected, you can use the toolchain mechanisms to let Gradle know about specific JDK installations.
All code contributions should contain the following:
@Issue("gradle/gradle#123")
.subprojects/docs/src/docs
). You can generate docs by running ./gradlew :docs:docs
.Your code needs to run on all supported Java versions and operating systems. The Gradle CI will verify this, but here are some pointers that will avoid surprises:
org.gradle.util.internal.TextUtil
class has some useful 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: ./gradlew :launcher:check
.
To try out a change in behavior manually, install Gradle locally and use it. Install: ./gradlew install -Pgradle_installPath=/any/path
. Use: /any/path/bin/gradle taskName
.
You can debug Gradle by adding -Dorg.gradle.debug=true
when executing. Gradle will wait for you to attach a debugger at localhost:5005
by default.
If you made changes to build logic in build-logic
, you can test them by executing ./gradlew :build-logic:check
.
The commit messages that accompany your code changes are an important piece of documentation, please follow these guidelines when writing commit messages:
Issue: #123
) in the commit message on a separate lineAfter you submit your pull request, a Gradle core developer will review it. It is normal that this takes several iterations, so don't get discouraged by change requests. They ensure the high quality that we all enjoy.
If you need to check on CI status as an external contributor, login as a guest.
Pull requests are automatically verified that all commit messages contain the Signed-off-by line with an email address that matches the commit author. In case you didn't sign off your commits before creating a pull request, you can still fix that to confirm that you agree to the terms of Developer Certificate of Origin.
To sign off a single commit:
git commit --amend --signoff
To sign off one or multiple commits:
git rebase --signoff origin/master
Then force push your branch:
git push --force origin test-branch
If you run into any trouble, please reach out to us on the issue you are working on.
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?