Permalink
Switch branches/tags
4.3 am-components am-jigsaw-hacks am-native-client am/build-finished-cleanup am/build-finished-errors am/build-init am/doc-tweak am/error-handling-cleanup am/flaky-test am/hide-warning am/init-update am/listener-failures am/map-property am/more-work-dep-cleanup am/plugins-block am/proj-state-cleanup am/prop-op am/props am/tapi-error-logging am/tapi-logging-again am/tapi-test-fix am/transform-deps andyrbell-npe-with-categories-and-cucumber-minimal bamboo-lacasseio-felipefzdz/hackathon bamboo/cache-kotlin-dsl-provider bamboo/deferred-notation-support-for-kotlin-lambda bamboo/fix-SamplesCodeQualityIntegrationTest bamboo/master/handle-deferred-values-uniformly bamboo/master/kotlin-dsl-snapshot bamboo/master/polish-build-scripts bamboo/master/polish-classycle bamboo/master/refine-kotlin-dsl-samples bamboo/optimize-gradleApi bamboo/public-api bamboo/release/kotlin-dsl-1.0.1 bamboo/release/kotlin-dsl-1.0.3 bamboo/release/kotlin-dsl-1.0.4 bamboo/release/kotlin-dsl-1.0.5 blindpirate/add-env-api blindpirate/add-project-name blindpirate/add-sign blindpirate/check-out-system-property blindpirate/disable-daemon-in-nodaemon-test blindpirate/disable-http-alive blindpirate/dogfood-junit5 blindpirate/dogfood/junit5 blindpirate/fail-fast blindpirate/fix-branch-name blindpirate/fix-hang-inputstream blindpirate/fix-on-release blindpirate/fix-windows-stream blindpirate/handle-cancel-status blindpirate/hang-example blindpirate/ignore-known-flaky blindpirate/improve-worker-classpath blindpirate/increase-flakytest-timeout blindpirate/java-9 blindpirate/java-11 blindpirate/java9-set-env blindpirate/kill-tree-on-windows blindpirate/merge-classpaths blindpirate/pmd-incremental blindpirate/repo-mirror-for-sample blindpirate/resource-coordination-hangs blindpirate/revert-integration-timeout blindpirate/revert-kotlin-dsk-104 blindpirate/set-mirror-for-groovy-snapshots blindpirate/set-up-gradle4-release-pipeline blindpirate/update-asciidoctor blindpirate/update-jetty blindpirate/upgrade-asciidoc blindpirate/use-file-channel blindpirate/version-control-variables bm-issue-1000 bm/android-smoke-tests bm/auto-applied/build-scan-in-script-plugin bm/canonical-maven-repo bm/dep-fail-on-unknown bm/dependency-lock bm/dependency-locking/generation bm/deprecation/no-search-upward bm/docs/dependency-management-code-location bm/flaky/pipe-closed bm/flaky/user-input bm/http-failure-blacklisting bm/java-10-config bm/java10-smoke-tests bm/revert-fail-on-first-repo-resolve-error bm/synchronized-event-listeners bm/upgrade-httpclient-version breskeby/container-callbacks-build-ops-plugins breskeby/container-callbacks-build-ops cc/add-incubation-reports cc/dependency-management/caching-rule-executor cc/dm/catch-exception cc/dm/detached-config-variant-aware cc/dm/do-not-leak-m2-pass-2 cc/dm/do-not-leak-m2 cc/dm/docs-5.0 cc/dm/dont-cache-patch-external-modules cc/dm/fix-kotlinjs cc/dm/forcing-platforms cc/dm/insight/fix-duplicates cc/dm/insight/show-rejected cc/dm/insight/2d-level-conflict cc/dm/issue-5920 cc/dm/issue-6403 cc/dm/java-platform-plugin cc/dm/platform-downgrade cc/dm/reduce-memory-pressure cc/dm/reusable-rule-test cc/dm/spike-moduleset-alignment cc/parallel-safe-tasks cc/poc-attributes-in-rules cc/provider-api/improvements dd/dm/report-version-constraints dd/5.0/remove-tapi-search-upward dl-convert-to-build-operation dl-generated-jar-show-name dl-issue-996 dl-zendesk-1582 dl/fixing-failing-test dl/native-forum-issue dl/xctest-task doc/custom_plugins doc/dependency_locking doc/groovy_plugin doc/init_scripts doc/managing_dependency_configurations doc/troubleshooting_dependency_resolution docs/5_0-breaking-changes-refactor donat/hackathon/deprecation-warnings donat/idea/mixed-sources-and-resources donat/scans/add-tc-metrics donat/update-teamcity-settings-dsl-to-2018.1 dummy-default-branch-for-tc eljobe/vcs/static-version eriwen/generate-bazel-projects eskatos-oehme-tomdcc/hackathon/after-evaluate-time-provenance eskatos/api/non-final eskatos/build/kotlin-dsl-plugin-version eskatos/distro/src-test eskatos/nullability/breaking-changes eskatos/plugins-dsl/built-in-plugins-in-script-plugins eskatos/pr/5762 ew-log-event-operation-descriptors ew/distributions/update-icons ew/docs-feedback-widget ew/docs/build-dashboard-kts ew/docs/build_environment_kts ew/docs/fix-7024 ew/docs/fix-pdf-relative-links ew/docs/reformed-release-notes ew/docs/sitemap ew/fix-6462 ew/javadoc-9 ew/logging/async-standard-logging ew/logging/group-all-the-logs ew/logging/group-plain-logs ew/logging/naive-plain-grouping ew/pr/7574 ew/release-notes-5.0 ew/update-joda-time feature/kotlin_dsl_organize felipe/ci-reliability/release-nightly fg/build-scan-plugin-2-0 gh-deadlock-detection gh-improved-taskplan gh-project-locking gh/hackathon/worker-api gh/issues/1233-again gh/issues/7580 gh/issues/7674 gh/lazy-tasks/idea-removal-error gh/lazy-tasks/legacy-gradle gh/logging/async-renderer gh/stable-native/build-with-architecture gh/stable-native/publish-architecure gh/stable-native/refactor-toolchains gh/stable-native/test-on-xcode10 gh/stable-native/unit-test-architecture gh/worker-api/set-executable guylabs/fail-early-on-incompatible-plugin-version hansd/cleanUpDaemons hansd/kotlinMigration hansd/kotlinScripts hansd/moduleType hansd/moveScriptsToBuildSrc jjohannes/archived/spock-1.1-rc-3 jjohannes/archived/worker-vm-heap-limits jjohannes/dependency-management/component-attributes-fix jjohannes/dependency-management/spike-versions-and-variants-listing jjohannes/experiment/distributed jjohannes/next-major-version jjohannes/tc-config-test jjustinic/docs/war-kts js/docs/add-notes-about-retries-to-dependency-management js/docs/remove-duplicate-heading js/javadoc/fix-search-functionality kotlin-dsl-docs kotlin-dsl-snapshot-release kotlin-dsl krro-scala-annotation-processor-classpath lacasseio/core/issue-4428 lacasseio/core/move-project-registration-earlier lacasseio/core/worker-kill-pattern lacasseio/flaky/avoid-using-jetty lacasseio/flaky/upgrade-jetty lacasseio/gradlebuild/fix-distributed-performance-test lacasseio/gradlebuild/lazy-task-conversion lacasseio/kotlin/build-script-conversion lacasseio/kotlin/convert-native-build-script lacasseio/lazy/allow-container-create lacasseio/lazy/allow-container-getByName lacasseio/lazy/avoid-concurrent-modification-when-realizing lacasseio/lazy/avoid-reaching-for-configurations lacasseio/lazy/avoid-using-disallowed-method-gradle-gradle lacasseio/lazy/container-matching-configureEach lacasseio/lazy/convert-sample-lazy lacasseio/lazy/disallow-container-modification lacasseio/lazy/disallow-container-register lacasseio/lazy/example-flaky-mutation lacasseio/lazy/issue-678 lacasseio/lazy/issue-6124 lacasseio/lazy/non-task-subject-mutation lacasseio/lazy/plugin-authoring lacasseio/lazy/pull-mutation-guard-higher lacasseio/lazy/removing-task-dependencies lacasseio/lazy/task-replacement lacasseio/native/allow-duplicate-target-machines lacasseio/native/msbuild-failure lacasseio/native/msbuild-slowness lacasseio/native/nostdinc lacasseio/native/optimize-flag lacasseio/native/provider-enhancement lacasseio/native/public-header-dependencies lacasseio/native/restrict-native-service lacasseio/native/static-variant lacasseio/native/tooling-api lacasseio/parallel-by-default/lock-properties lacasseio/perf/incremental-build-4.2.1 lacasseio/perf/no-system-includes lacasseio/perf/some-work lacasseio/pr-6176 lacasseio/provider/disallow-mutation ldaley/scan-end-of-build-notify ljacomet/dependency-management/align-force ljacomet/dependency-management/alignment-fixes ljacomet/dependency-management/perf-investigation ljacomet/dependency-management/publish-warning ljacomet/dependency-management/removal-on-deselect lptr/core/new-scheduler lptr/local-merkle-cache lptr/services/root-settings-evaluated-scope lukeu-lukeu/ide/eclipse-project-whenMerged-in-buildship marc/fixes/1431-reduce-contention marc/insights/spike/fine-grained-events marc/insights/spike/profile-api marc/insights/spike/profile-event marc/issues/1412-journal-snapshot marc/issues/1711-document-wrapper-checksum-verification master oehme/layered-evaluation oehme/performance/kotlin-comparison oehme/performance/no-retries oehme/timeouts/jstack oehme/update-wrapper oehme/war-public-api pl/nav-iteration-5 pm/jvm-software-model/jdk-discovery pm/plugins-dsl/script-plugins pm/workers/compilation-workers-spike release-4.10 release revert-4405-master revert-5275-bamboo/dont-pass-empty-cp sg-gradlephant-status sg/classycle sg/daemon/errors sg/daemon/version sg/hacks sg/lazy/containers sg/lazy/deincubate sg/lazy/kotlindsl sg/lazy/native-plugins sg/lazy/publish-register sg/lazy/rework sg/native/google-test-poc sg/native/os-factory sg/native/relative-paths sg/perf/ant-excludes sg/perf/faster-build-cache sg/perf/faster sg/perf/newplugin sg/play/worker-api sg/remove-logging sg/scala/argh sg/swift/faster-caching sg/variants sw-ignore-files-on-classpath-start sw/build-cache/diagnose-individual-input-md5s td/bump-build-scan-compatibility-1-13 td/lifecycle-callback-instrumentation-spike teamcity-versioned-settings wl-dry-run-docs wl-log-grouping-spec wolfs/core/no-catch-throwable wolfs/de-incubate/software-model wolfs/file-system-mirror/fix-path-on-element wolfs/file-system-mirror/polish-builders wolfs/hackathon/task-graph wolfs/performance-tests/better-inputs wolfs/performance/G1 wolfs/rich-inputs/simple-system-properties wolfs/samples/no-default-sample-dir wolfs/timeout-for-build-progress-cross-version wolfs/xforms/dependency-classpath wolfs/xforms/execution-history-review wolfs/xforms/no-cached-result wolfs/xforms/spike-properties wolfs/xforms/with-build-cache wolfs/xforms/workspace-services
Nothing to show
Find file Copy path
138 lines (79 sloc) 6.43 KB

Contributing to Gradle

Thank you for considering a contribution 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

Get in touch

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:

  • Why is this change done? What's the use case?
  • What will the API look like? (For new features)
  • 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)

This can be done directly inside the GitHub issue or (for large changes) you can share a Google Doc with us.

Reporting Security Issues

Please do not report security issues to the public issue tracker. Please send security issues to security@gradle.com.

Accept Developer Certificate of Origin

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.

Follow the Code of Conduct

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

Making Changes

Development Setup

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

IntelliJ

You can generate the IntelliJ projects by running

./gradlew idea

then open the generated gradle.ipr file.

Eclipse

You can generate the Eclipse projects by running

./gradlew eclipse

Then you can import the generated projects into Eclipse

  1. Install Eclipse 4.5 (Mars) at least
  2. Install the Groovy Eclipse plugin from http://dist.springsource.org/snapshot/GRECLIPSE/e4.5/
  3. Make sure you have a Java 8 compatible JDK configured in your workspace
  4. In Window->Preferences->Groovy->Compiler, check Enable Script folder support and add **/*.gradle
  5. Import all projects using the "Import Existing Projects into Workspace" wizard

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 @Issue("gradle/gradle#123").
  • Documentation in the User Guide and DSL Reference (under 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:

  • Avoid using features introduced in Java 1.7 or later. Several parts of Gradle still need to run on Java 6.
  • Normalise file paths in tests. The org.gradle.util.TextUtil class has some useful functions for this purpose.

Development Workflow

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.

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 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
  • Sign off your commits to indicate that you agree to the terms of Developer Certificate of Origin.

Submitting Your Change

After 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.

Signing Off Commits After Submitting a Pull Request

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 filter-branch --msg-filter "cat - && echo && echo 'Signed-off-by: Your Name <Your.Name@example.com>'" HEAD

Then force push your branch:

git push --force origin test-branch

Getting Help

If you run into any trouble, please reach out to us on the issue you are working on.

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?