Skip to content

Latest commit

 

History

History
183 lines (106 loc) · 9.6 KB

CONTRIBUTING.md

File metadata and controls

183 lines (106 loc) · 9.6 KB
Raw

Contributing to Gradle

Thank you for contributing to Gradle! This guide explains how 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. 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.

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.

Setting up your development environment

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

Import Gradle into IntelliJ

To import Gradle into IntelliJ:

  • Open the build.gradle.kts file with IntelliJ and choose "Open as Project"
  • Make sure "Create separate module per source set" is selected
  • Make sure "Use default gradle wrapper" is selected
  • Select a Java 11 VM as "Gradle JVM"
  • In the "File already exists" dialogue, choose "Yes" to overwrite
  • In the "Open Project" dialogue, choose "Delete Existing Project and Import"
  • 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 Java 11 SDK installed before importing the project into IntelliJ and after adding a Java 11 SDK your IntelliJ still uses the wrong SDK version, you might need to invalidate IntelliJ's caches before reloading the project.

Making your change

Code change guidelines

All code contributions should contain the following:

  • Create unit tests using Spock for new classes or methods that you introduce.
  • Create integration tests that exercise a Gradle build for the bug/feature.
  • Annotate tests that correspond to a bug on GitHub (@Issue("https://github.com/gradle/gradle/issues/2622")).
  • Add documentation to the User Manual and DSL Reference (under subprojects/docs/src/docs). You can generate docs by running ./gradlew :docs:docs.
  • 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 1.7 or later. Some parts of Gradle still need to run on Java 6.
  • Normalize file paths in tests. The org.gradle.util.internal.TextUtil class has some useful functions for this purpose.

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:

  1. Run tests.
  • Run ./gradlew :<subproject>:quickTest where <subproject> is the name of the subproject you've changed.
  • For example: ./gradlew :launcher:quickTest.
  1. 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.

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 login as "guest".

Useful tips

Debugging Gradle

You can debug Gradle by adding -Dorg.gradle.debug=true to the command-line. Gradle will wait for you to attach a debugger at localhost:5005 by default.

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

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.

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-settings/cc-experiment-plugin/src/main/kotlin/gradlebuild.internal.cc-experiment.settings.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.

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

./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 subprojects/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?