New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include Kotlin DSL samples in all user manual chapters #6442

Closed
eriwen opened this Issue Aug 20, 2018 · 12 comments

Comments

Projects
None yet
6 participants
@eriwen
Member

eriwen commented Aug 20, 2018

Kotlin DSL 1.0 RC is upon us. 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 user manual in Gradle nightly distribution have a Kotlin DSL sample alongside the 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.

  • Setup your environment for developing Gradle. Don't forget to set at java9Home Gradle property! (e.g. echo "systemProp.java9Home=/Library/Java/JavaVirtualMachines/jdk-9.0.4.jdk/Contents/Home" >> ~/.gradle/gradle.properties)
  • Submit an empty pull request titled "Include Kotlin DSL samples for chapter (chapter_name)" or write a comment on this issue for 1 user manual chapter (at a time). See the table below or consult the list of all chapters.
  • Open the appropriate chapter under the subprojects/docs/src/docs/userguide/ in your gradle/gradle clone.
  • Generate the user manual by running ./gradlew :docs:userguide -x :docs:userguideSinglePage and serving the content under subprojects/docs/build/docs.
  • For each "Example" in the .adoc file in question, create a multi-language sample listing. You will 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/gradle/pull/6508/files#diff-ce02749237d61352d70ff3c9746a5e59R58

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 will be helpful here in addition to Kotlin DSL samples.

  • After making changes, run samples tests using ./gradlew :integTest:integTest --tests "UserGuideSamplesIntegrationTest" or even a subset with ./gradlew :integTest:integTest --tests "UserGuideSamplesIntegrationTest.*foobar*"
  • 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: #6434 #6406 #6424

If you get stuck, reach out to us through the #kotlin-dsl channel on Gradle Community Slack. Invite link.

Remaining Work

Chapter # Samples Status

@eriwen eriwen added the in:docs label Aug 20, 2018

@eriwen eriwen added this to the 5.0 milestone Aug 20, 2018

@eriwen eriwen added the epic label Aug 20, 2018

@eriwen eriwen modified the milestones: 5.0, 5.0 RC1 Aug 20, 2018

@eriwen eriwen self-assigned this Aug 22, 2018

@StefMa

This comment has been minimized.

Show comment
Hide comment
@StefMa

StefMa Aug 23, 2018

Contributor

Hey @eriwen
you can assign me the ./java_gradle_plugin.adoc 👍

Contributor

StefMa commented Aug 23, 2018

Hey @eriwen
you can assign me the ./java_gradle_plugin.adoc 👍

@StefMa StefMa referenced this issue Aug 23, 2018

Closed

Kotlin dsl for java gradle plugin #6485

5 of 11 tasks complete

jnizet added a commit to jnizet/gradle that referenced this issue Aug 23, 2018

include Kotlin DSL samples for chapter base_plugin
refs gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 23, 2018

include Kotlin DSL samples for chapter base_plugin
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 23, 2018

include Kotlin DSL samples for chapter base_plugin
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

fix: remove the double "Example" prefix in base_plugin doc
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter java_library_plugin
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter java_library_plugin
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter java_library_plugin
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

include Kotlin DSL sample for chapter working_with_dependencies
Issue gradle#6442

Signed-off-by: jnizet <jb@ninja-squad.com>
@jnizet

This comment has been minimized.

Show comment
Hide comment
@jnizet

jnizet Aug 24, 2018

Contributor

I'm working on working_with_files.adoc

Contributor

jnizet commented Aug 24, 2018

I'm working on working_with_files.adoc

jnizet added a commit to jnizet/gradle that referenced this issue Aug 24, 2018

@StefMa StefMa referenced this issue Sep 4, 2018

Merged

Kotlin DSL for Organizing Gradle Projects #6621

5 of 11 tasks complete

oehme added a commit that referenced this issue Sep 5, 2018

include Kotlin DSL sample for chapter dependency_management_for_java_…
…projects (dependencyBasics example)

Issue #6442

Signed-off-by: jnizet <jb@ninja-squad.com>

oehme added a commit that referenced this issue Sep 5, 2018

include Kotlin DSL sample for chapter dependency_management_for_java_…
…projects (externalDependencies example)

This example is also used in dependency_types, so I modified it, too.

Issue #6442

Signed-off-by: jnizet <jb@ninja-squad.com>

oehme added a commit that referenced this issue Sep 5, 2018

include Kotlin DSL sample for chapter dependency_management_for_java_…
…projects (defineRepository example)

This example is also used in repository_types, so I modified it, too.

Issue #6442

Signed-off-by: jnizet <jb@ninja-squad.com>

@eskatos eskatos self-assigned this Sep 7, 2018

@mkobit

This comment has been minimized.

Show comment
Hide comment
@mkobit

mkobit Sep 17, 2018

Contributor

What about the guides at https://guides.gradle.org ?

EDIT: looks like at least one already has it - https://guides.gradle.org/writing-gradle-plugins/

Contributor

mkobit commented Sep 17, 2018

What about the guides at https://guides.gradle.org ?

EDIT: looks like at least one already has it - https://guides.gradle.org/writing-gradle-plugins/

@StefMa

This comment has been minimized.

Show comment
Hide comment
@StefMa

StefMa Sep 17, 2018

Contributor
Contributor

StefMa commented Sep 17, 2018

@jnizet

This comment has been minimized.

Show comment
Hide comment
@jnizet

jnizet Sep 17, 2018

Contributor

@mkobit @StefMa several of them have already been translated. I translated one or two of them IIRC. The main difference is that these guides don't use exemplar for tests, and the way tests are written varies from guide to guide.
Many guides also use deprecated configurations (compile, etc.), and use the imperative way of applying plugins, too.

Contributor

jnizet commented Sep 17, 2018

@mkobit @StefMa several of them have already been translated. I translated one or two of them IIRC. The main difference is that these guides don't use exemplar for tests, and the way tests are written varies from guide to guide.
Many guides also use deprecated configurations (compile, etc.), and use the imperative way of applying plugins, too.

@eriwen

This comment has been minimized.

Show comment
Hide comment
@eriwen

eriwen Sep 18, 2018

Member

We do want to convert the guides, too. @jnizet is right that we'd probably want to convert them to use Exemplar for testing (most don't yet). It's tougher for me to write instructions because some guides use slightly different plugins/libraries.

That all said, I probably will put together a similar issue to this one on the gradle/guides board and at any time happy to help contributors eager to improve guides. Please reach out.

Member

eriwen commented Sep 18, 2018

We do want to convert the guides, too. @jnizet is right that we'd probably want to convert them to use Exemplar for testing (most don't yet). It's tougher for me to write instructions because some guides use slightly different plugins/libraries.

That all said, I probably will put together a similar issue to this one on the gradle/guides board and at any time happy to help contributors eager to improve guides. Please reach out.

@marcphilipp marcphilipp modified the milestones: 5.0 M1, 5.0 RC1 Oct 2, 2018

@eskatos

This comment has been minimized.

Show comment
Hide comment
@eskatos

eskatos Oct 15, 2018

Member

This is now done! Thank you all!

Member

eskatos commented Oct 15, 2018

This is now done! Thank you all!

@eskatos eskatos closed this Oct 15, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment