Thank you for considering making a contribution to Gradle Kotlin DSL Samples! This guide explains how to setup your environment for development and where to get help if you encounter trouble.
This repository (gradle/kotlin-dsl) contains extra samples for the Gradle Kotlin DSL only. If you intend to contribute an extra sample keep reading.
The Gradle Kotlin DSL code can be found in the gradle/gradle git repository in the :kotlinDsl* sub-projects.
Please direct your contributions to that repository and see how to contribute to Gradle.
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/.
In order to make changes to the Gradle Kotlin DSL Samples, you'll need:
- A text editor or IDE. We use and recommend the very latest IntelliJ IDEA CE.
- A Java Development Kit (JDK) version 1.8 or higher
- git and a GitHub account
Gradle Kotlin DSL uses a pull request model for contributions. Fork gradle/kotlin-dsl and clone your fork.
Configure your Git username and email with
git config user.name 'First Last'
git config user.email user@example.com
Before importing the project into IntelliJ IDEA make sure to run ./gradlew check at least once so all required files are generated.
Samples are located in the samples/ directory of this repository.
To add a new sample, simply create a new directory under samples/. That directory must include a Gradle Wrapper, please copy it from another sample directory.
A test runs tasks on each sample, so your new sample will automatically be smoke-tested. Please consider adding a more precise test.
Samples are tested using gradle/exemplar. If your test can be expressed using exemplar external samples, add the configuration files to subprojects/samples-tests/src/exemplar/samples/$yourSampleDir. Otherwise please add a JUnit based test in subprojects/samples-tests/src/test/kotlin extending from AbstractSampleTest.
After making changes, you can test them by running ./gradlew check.
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.
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 (
See #123) in the commit message on a separate line - Sign off your Git commits to indicate that you agree to the terms of Developer Certificate of Origin.
All code contributions should be submitted via a pull request from a forked GitHub repository.
Once received, the pull request will be reviewed by a Gradle Kotlin DSL developer.
If you run into any trouble, please reach out to us in the #kotlin-dsl channel of the Gradle Community Slack.
- The Gradle Kotlin DSL Primer is a must read.
- The Gradle user manual and guides contain Kotlin DSL build script samples that demonstrate how to use all Gradle features.
- Some diagrams provide a good overview of how the Kotlin DSL is structured and interacts with Gradle, Gradle plugins, IDEs.
We deeply appreciate your effort toward improving Gradle. If you enjoyed this process, perhaps you should consider getting paid to develop Gradle?