Contributing to the Gradle Build Tool

Thank you for your interest in contributing to Gradle! This guide explains how to contribute to the core Gradle components, extensions and documentation located in this repository. For other extensions and components, see the Gradle Community Resources.

This guide will help you to...

maximize the chance of your changes being accepted
work on the Gradle code base
get help if you encounter trouble

Before you start

Before starting to work on a feature or a bug fix, please open an issue to discuss the use case or bug with us, or post a comment in the relevant issue. This can save everyone a lot of time and frustration.

For any non-trivial change, we need to be able to answer these questions:

Why is this change done? What's the use case?
For user-facing features, what will the API look like?
What test cases should it have? What could go wrong?
How will it roughly be implemented? We'll happily provide code pointers to save you time.

We may ask you to answer these questions directly in the GitHub issue or (for large changes) in a shared Google Doc.

Please note that some features may be out of the team's current focus, and it can take significant time for the team to review the PR thoroughly and address it fully.

Security vulnerabilities

Do not report security vulnerabilities to the public issue tracker. Follow our Security Vulnerability Disclosure Policy.

Follow the Code of Conduct

Contributors must follow the Code of Conduct outlined at https://gradle.org/conduct/.

Additional help

If you run into any trouble, please reach out to us on the issue you are working on. There is a #contributing channel on the community Slack which you can use to ask any questions.

Finding issues to work on

If you are looking for good first issues, take a look at the list of good first issues that should be actionable and ready for a contribution.

If you are looking for a contribution that is more substantial, you can look at the help wanted issues. These issues are more complex and might be challenging for first-time contributors.

You can share your interest in fixing the issue by commenting on it. If somebody shared their interest in the issue, please consider letting them work on it. However, if there are no changes for more than a week, it's safe to assume that the issue is up for grabs. There is no need to ask for an assignment or for permission to work on those issues, just comment and start working on it.

Setting up your development environment

In order to make changes to Gradle, you'll need:

Adoptium JDK (Java Development Kit) version 17. Fixed version is required to use remote cache.
A text editor or IDE. We use and recommend IntelliJ IDEA CE. IntelliJ Ultimate will also work. You'll need IntelliJ 2021.2.2 or newer.
git and a GitHub account.

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

IntelliJ IDEA

Import Gradle into IntelliJ

To import Gradle into IntelliJ:

Open the build.gradle.kts file in root of the project with IntelliJ and choose "Open as Project"
Select a Adoptium Java 17 VM as "Gradle JVM"
Revert the Git changes to files in the .idea folder

NOTE: Due to the project size, the very first 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.

If you did not have a Adoptium Java 17 SDK installed before importing the project into IntelliJ and after adding Adoptium Java 17 SDK your IntelliJ still uses the wrong SDK version, you might need to invalidate IntelliJ's caches before reloading the project.

Install Develocity IntelliJ plugin

Consider installing the Develocity IntelliJ plugin to bring real-time Gradle build analysis directly into your IDE. It helps developers optimize performance and gain deeper insights into their builds.

Making your change

Code change guidelines

Code contributions should follow these guidelines to maximize the chance of them being accepted:

Cover your code with tests. See the Testing guide for more information.
Add documentation to the User Manual and DSL Reference (under platforms/documentation/docs/src/docs).
For error messages related changes, follow the ErrorMessages Guide.
Add Javadoc for new methods and classes, following the Javadoc Style Guide. Javadoc is required for new public, top-level types.
For new features, the feature should be mentioned in the Release Notes.

Your code needs to run on all versions of Java that Gradle supports and across all supported operating systems (macOS, Windows, Linux). The Gradle CI system will verify this, but here are some pointers that will avoid surprises:

Be careful when using features introduced in Java 9 or later. Some parts of Gradle still need to run on Java 8.
Normalize file paths in tests. The org.gradle.util.internal.TextUtil class has some useful functions for this purpose.

You can consult the Architecture documentation to learn about some of the architecture of Gradle.

Contributing to documentation

This repository includes Gradle documentation sources, including but not limited to: User Manual, DSL Reference and Javadoc. This information is used to generate documentation for each Gradle version on docs.gradle.org. The documentation is mostly implemented in Asciidoc though we use GitHub-flavored Markdown for internal documentation too.

You can generate docs by running ./gradlew :docs:docs. This will build the whole documentation locally in platforms/documentation. For more commands and examples, including local development, see this guide.

Creating commits and writing commit messages

The commit messages that accompany your code changes are an important piece of documentation. Please follow these guidelines when creating commits:

Write good commit messages.
Sign off your commits to indicate that you agree to the terms of Developer Certificate of Origin. We can only accept PRs that have all commits signed off.
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.

Testing changes

After making changes, you can test your code in 2 ways:

Run tests

Run ./gradlew :<subproject>:quickTest where <subproject> is the name of the subproject you've changed.
For example: ./gradlew :launcher:quickTest.

Install Gradle locally

and try out a change in behavior manually.

Install: ./gradlew install -Pgradle_installPath=/any/path
Use: /any/path/bin/gradle taskName.

It's also a good idea to run ./gradlew sanityCheck before submitting your change because this will help catch code style issues.

NOTE: Do NOT run gradle build on the local development environment, even if you have Gradle or Develocity build caching enabled for the project. The Gradle Build Tool repository is massive, and it will take ages to build on a local machine without necessary parallelization and caching. The full test suites are executed on the CI instance for multiple configurations, and you can rely on it after doing initial sanity check and targeted local testing.

Copyright and License

When updating/modifying a file, please do not make changes to the copyright header.

When creating a new file, please make sure to add a header as defined below.

Required Files for Copyright Headers:

Source code files (e.g., .java, .kt, .groovy).
Documentation files, where applicable (e.g., .adoc, .md).

Exempt Files for Copyright Headers:

Scripts critical to builds, CI, or deployment (e.g., .kts, .groovy).
Auto-generated files (e.g., by code generators).
Minor configuration files (e.g., .gitignore).
Documentation samples and code snippets (e.g., .java, .kt, .groovy, .kts).
Release notes (e.g., .md).
READMEs (e.g., .md).

Copyright Header for Source Files:

/*
 * Copyright [YEAR OF FILE CREATION] Gradle and contributors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Copyright Header for Documentation Files:

/*
 * Copyright [YEAR OF FILE CREATION] Gradle and contributors.
 *
 * Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://creativecommons.org/licenses/by-nc-sa/4.0/
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Submitting Your Change

After you submit your pull request, a Gradle developer will review it. It is normal for this to take 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, you can click "Log in as guest".

Useful tips

How Gradle Works

We have a series of blog that explains how Gradle works. This may help you better understand and contribute to Gradle.

Debugging Gradle

See the Debugging Gradle guide for tips on debugging Gradle.

If you made changes to build logic in the build-logic included build, you can run its tests by executing ./gradlew :build-logic:check.

Fixing DCO failures/Signing Off Commits After Submitting a Pull Request

You must agree to the terms of Developer Certificate of Origin by signing off your commits. We automatically verify that all commit messages contain a Signed-off-by: line with your email address. We can only accept PRs that have all commits signed off.

If you didn't sign off your commits before creating the pull request, you can fix that after the fact.

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

Fixing sanity check failures after public API changes

If your PR includes any changes to the Gradle Public API, it will cause the binary compatibility check to fail. The binary compatibility check runs as a part of the broader sanity check. The latter runs on every PR and is a prerequisite for merging.

If you run the sanity check locally with the ./gradlew sanityCheck, you can see the binary compatibility error in the output. It looks like the following:

Execution failed for task ':architecture-test:checkBinaryCompatibility'.
> A failure occurred while executing me.champeau.gradle.japicmp.JApiCmpWorkAction
   > Detected binary changes.
         - current: ...
         - baseline: ...
     
     See failure report at file:///<path to Gradle checkout>/subprojects/architecture-test/build/reports/binary-compatibility/report.html

Here are the steps to resolve the issue:

Open the failure report mentioned in the output.
If you don't see the report link in the output in the IDE, make sure to select the top-level node in the structured output panel. The report will explain the errors in detail. Perhaps, you forgot to add an @Incubating annotation or @since in the javadoc.
Accept the changes.
If you are sure that the changes are intentional, follow the steps described in the report. This includes adding the description of the changes to the accepted-public-api-changes.json file, and providing a reason for each change. You can add the changes to any place in the file, e.g. at the top.
Make sure the file with accepted changes is sorted.
Use the ./gradlew :architecture-test:sortAcceptedApiChanges task to sort the file.
Validate your changes before committing.
Run the ./gradlew sanityCheck task again to make sure there are no more errors.

Filtering changes by severity

There is a somewhat non-obvious filter present on the page that allows you to control which type of messages are displayed. The filter is a dropdown box that appears when you click the Severity ⬇️ label in the black header bar to the immediate right of the Gradle version.

If you have a large number of messages of different types, filtering by severity to see only Errors can be helpful when processing the report. Errors are the only type of issues that must be resolved for the checkBinaryCompatibility task to succeed.

You can set the 'bin.cmp.report.severity.filter' property in your gradle.properties to one of the available values in the dropdown box to automatically filter issues to that severity level upon opening this report.

Accepting multiple changes

If you have multiple changes to accept (and you're sure they ought to be accepted instead of corrected), you can use the Accept Changes for all Errors button to speed the process. This button will cause a Javascript alert dialog to appear asking you to type a reason for accepting the changes, e.g. "Added new API for Gradle 8.x".

Clicking okay on the dialog will cause a copy of the accepted-public-api-changes.json containing your (properly sorted) addition to be downloaded. You can then replace the existing file with this new downloaded version.

Java Toolchain

The Gradle build uses Java Toolchain support to compile and execute tests across multiple versions of Java.

Available JDKs on your machine are automatically detected and wired for the various compile and test tasks. Some tests require multiple JDKs to be installed on your computer, be aware of this if you make changes related to anything toolchains related.

If you want to explicitly run tests with a different Java version, you need to specify -PtestJavaVersion=# with the major version of the JDK you want the tests to run with (e.g. -PtestJavaVersion=14).

Configuration cache enabled by default

The build of Gradle enables the configuration cache by default as a dogfooding experiment.

Most tasks that are used to build Gradle support the configuration cache, but some don't. For example, building the documentation currently requires you to disable the configuration cache.

To disable the configuration cache, run the build with --no-configuration-cache.

Tasks known to have problems are listed in the build logic. You can find this list at:

build-logic/root-build/src/main/kotlin/gradlebuild.internal.cc-experiment.gradle.kts

If you discover a task that doesn't work with the configuration but it not in this list, please add it.

For more information on the configuration cache, see the user manual.

Remote build cache

Gradle, Inc runs a set of remote build cache nodes to speed up local builds when developing Gradle. By default, the build is configured to use the build cache node in the EU region.

The build cache has anonymous read access, so you don't need to authenticate in order to use it. You can use a different build cache node by specifying -Ddevelocity.edge.discovery=false -DcacheNode=us for a build cache node in the US or -Ddevelocity.edge.discovery=false -DcacheNode=au for a build cache node in Australia.

If you are not getting cache hits from the build cache, you may be using the wrong version of Java. A fixed version (Java 11) is required to get remote cache hits.

Building a distribution from source

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 packaging/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:

./gradlew 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 packaging/distributions-full/build/distributions/gradle-<version>-all.zip. You can then use it as a Gradle Wrapper local distribution:

./gradlew wrapper --gradle-distribution-url=file:/path/to/gradle-<version>-all.zip

Our thanks

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?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!