gradle / gradle/guides

Provide Kotlin DSL examples in all guides

Open
#191 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help-wanted
Dominant language
Java
Stars
48
Forks
36
Avg merge
7h 37m
Merged PRs (30d)
8

Description

The Kotlin DSL is now 1.x! Now that the APIs are stable, it is time for Kotlin DSL examples to be displayed everywhere in Gradle documentation that the Groovy DSL is.

This epic will be considered complete when all samples within the [Gradle guides](https://guides.gradle.org/) have a Kotlin DSL sample alongside each Groovy DSL sample.

### Contributor Instructions

If you are familiar with the Gradle Kotlin DSL and want to help the project reach the 1.0 milestone.

- [ ] Submit a pull request titled "Include Kotlin DSL samples" or write a comment on this issue for 1 guide (at a time). See the table below or consult the [list of all chapters](https://github.com/gradle/gradle/tree/master/subprojects/docs/src/docs/userguide).
- [ ] Clone the appropriate repo from https://github.com/gradle-guides
- [ ] Generate the guide by running `./gradlew :asciidoctor` and serving the content under `build/html5`.
- [ ] For each sample in the `.adoc` file in question, create a [multi-language sample listing](https://github.com/gradle/gradle/tree/master/subprojects/docs#code-samples). You may have to move around files and create a sibling `kotlin/` project which should have identical functionality to the `groovy/` one, `include` the Groovy and Kotlin samples next to each other, and configure the sample tests. _Don't forget to update any tests/other documents that reference the given sample._

This is a diff that shows what this looks like: https://github.com/gradle-guides/implementing-gradle-plugins/commit/7e169d9c1563f6953e390cafe42473180df389e0

When writing Kotlin DSL samples please:
- keep them as similar as possible to the Groovy sample
- make both Groovy and Kotlin samples prefer the `plugins {}` block to apply plugins
- make sure all sample builds have a `settings.gradle` or `settings.gradle.kts` file and a reasonable `rootProject.name`
- do not adopt the lazy configuration API or overuse Kotlin language features
- if you find any missing type-safe member in the Gradle API then create an issue on `gradle/gradle` and work around it by e.g. leveraging `closureOf(..)` or `withGroovyBuilder {}`

The [Migrating from Groovy to Kotlin DSL guide](https://guides.gradle.org/migrating-build-logic-from-groovy-to-kotlin/) will be helpful here in addition to [Kotlin DSL samples](https://github.com/gradle/kotlin-dsl/tree/master/samples).

- [ ] After making changes, run samples tests using `./gradlew :check`
- [ ] Push to your branch and let us know it's ready for review.
- [ ] Address any feedback to get your pull request merged. Congratulations! Email developer-experience@gradle.com with a link to your first merged pull request and we'll send you Gradle swag as thanks!

Example PRs for inspiration: gradle/gradle#6434 gradle/gradle#6406 gradle/gradle#6424

If you get stuck, reach out to us through the `#kotlin-dsl` channel on [Gradle Community Slack](https://gradle-community.slack.com/). [Invite link](https://join.slack.com/t/gradle-community/shared_invite/enQtNDE3MzAwNjkxMzY0LTYwMTk0MWUwN2FiMzIzOWM3MzBjYjMxNWYzMDE1NGIwOTJkMTQ2NDEzOGM2OWIzNmU1ZTk5MjVhYjFhMTI3MmE).

### Remaining Work

| Guide | Assignee |
| --- | --- |
| gradle-guides/building-groovy-libraries | [in progress](https://github.com/gradle-guides/building-groovy-libraries/pull/5) |
| gradle-guides/building-java-9-modules | NOT_TAKEN |
| gradle-guides/building-java-applications | ✅ |
| gradle-guides/building-java-web-applications | ✅ |
| gradle-guides/building-kotlin-jvm-libraries | ✅|
| gradle-guides/building-scala-libraries | NOT_TAKEN |
| gradle-guides/building-spring-boot-2-projects-with-gradle | NOT_TAKEN |
| gradle-guides/creating-multi-project-builds | ✅ |
| gradle-guides/consuming-jvm-libraries | NOT_TAKEN |
| gradle-guides/designing-gradle-plugins | NOT_TAKEN |
| gradle-guides/executing-gradle-builds-on-jenkins | N/A |
| gradle-guides/executing-gradle-builds-on-teamcity | N/A |
| gradle-guides/executing-gradle-builds-on-travisci | N/A |
| gradle-guides/gradle-site-plugin | ✅|
| gradle-guides/migrating-from-maven | ✅ |
| gradle-guides/publishing-plugins-to-gradle-plugin-portal | ✅ |
| gradle-guides/running-webpack-with-gradle | NOT_TAKEN |
| gradle-guides/testing-gradle-plugins | NOT_TAKEN |
| gradle-guides/using-the-worker-api | NOT_TAKEN |
| gradle-guides/writing-getting-started-guides | N/A |
| gradle-guides/writing-gradle-plugins | ✅ |
| gradle-guides/writing-gradle-tasks | ✅ |

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Choose one NOT_TAKEN guide from the remaining-work table and inspect its .adoc samples and existing Groovy projects. Clone the relevant gradle-guides repository, run ./gradlew :asciidoctor, and use the displayed output to add corresponding Kotlin samples and listings. Run ./gradlew :check; done means every sample in that guide has a working Kotlin DSL counterpart and related tests or references are updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.