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

Getting started building Kotlin libraries #95

Closed
pioterj opened this Issue Apr 7, 2017 · 6 comments

Comments

Projects
None yet
4 participants
@pioterj
Member

pioterj commented Apr 7, 2017

Kotlin is getting more popular, especially in Android projects. JetBrains provides official Kotlin Gradle plugin. See https://kotlinlang.org/docs/reference/using-gradle.html. I asked them if they are interested in contributing a getting started guide.

@pioterj pioterj referenced this issue Jul 20, 2017

Open

Building JVM projects #79

6 of 9 tasks complete

@eriwen eriwen self-assigned this Sep 6, 2017

eriwen added a commit to gradle-guides/building-kotlin-jvm-libraries that referenced this issue Sep 8, 2017

@pioterj

This comment has been minimized.

Show comment
Hide comment
@pioterj

pioterj Sep 11, 2017

Member

@eriwen The guide looks good to me!

Here's my feedback:

  • Using Kotlin DSL is an interesting choice and may attract more people interested in Kotlin.
  • I like providing a complete example. I think it should be a practice for all guides.
  • I'd consider dropping "JVM" from the title. We don't have it for Java and Scala library guides.
  • There's a typo in MyLbraryTest.kt
Member

pioterj commented Sep 11, 2017

@eriwen The guide looks good to me!

Here's my feedback:

  • Using Kotlin DSL is an interesting choice and may attract more people interested in Kotlin.
  • I like providing a complete example. I think it should be a practice for all guides.
  • I'd consider dropping "JVM" from the title. We don't have it for Java and Scala library guides.
  • There's a typo in MyLbraryTest.kt
@bmuschko

This comment has been minimized.

Show comment
Hide comment
@bmuschko

bmuschko Sep 11, 2017

@eriwen Looking good. I have a couple of comments.

  • Other getting started guides do not spell out "step x". We should align.
  • A short introduction would be helpful to tell the user what is going to be discussed (see other guides). Maybe also point readers to a short intro to Kotlin if they are not familiar.
  • Language in Javadocs should use {@code } instead.
  • "Create project directory" raises the question why there's no init task support like for other languages. I understand why but maybe spell it out to the reader. IMHO init should become a public API that lets you define your own definition. That could become part of the external Kotlin plugin.
  • Is this import org.gradle.kotlin.dsl.* only needed for the kotlin method? If yes, then let's not use *.
  • "You’ll notice that we’re using the new implementation dependency configuration." I really don't like it when we say "new". We made the same mistake with the publishing plugins. Let's just remove "new" and use it as best practice.
  • Listing that uses build-scan seems to have a rendering issue (marked green). Or was that intentional? I believe users will copy/paste that. This is the first time we do that in a guide.
  • "Digging deeper with a build scan". Apart from seeing that the Kotlin plugin was applied in a build scan I don't quite the benefit of having a full section on the build scan. Can we maybe find a better use case later in the guide where we actually get additional information on a problem a reader is facing? Or is this more about the syntax?
  • "The Dokka Gradle plugin cannot be resolved from the Gradle Plugin Portal as of v0.9.15" - We should ask Jetbrains to publish it there.
  • "Configure project coordinates to org.example:my-kotlin-library:0.0.1" - Should also annotate the version property.
  • Instead of have the almost exact same code in multiple subdirectories, I'd just include specific portions of a file from a single source code example: https://github.com/gradle-guides/building-kotlin-jvm-libraries/tree/master/samples/code. If you'd need to fix one example then you'll likely have to fix them all.

bmuschko commented Sep 11, 2017

@eriwen Looking good. I have a couple of comments.

  • Other getting started guides do not spell out "step x". We should align.
  • A short introduction would be helpful to tell the user what is going to be discussed (see other guides). Maybe also point readers to a short intro to Kotlin if they are not familiar.
  • Language in Javadocs should use {@code } instead.
  • "Create project directory" raises the question why there's no init task support like for other languages. I understand why but maybe spell it out to the reader. IMHO init should become a public API that lets you define your own definition. That could become part of the external Kotlin plugin.
  • Is this import org.gradle.kotlin.dsl.* only needed for the kotlin method? If yes, then let's not use *.
  • "You’ll notice that we’re using the new implementation dependency configuration." I really don't like it when we say "new". We made the same mistake with the publishing plugins. Let's just remove "new" and use it as best practice.
  • Listing that uses build-scan seems to have a rendering issue (marked green). Or was that intentional? I believe users will copy/paste that. This is the first time we do that in a guide.
  • "Digging deeper with a build scan". Apart from seeing that the Kotlin plugin was applied in a build scan I don't quite the benefit of having a full section on the build scan. Can we maybe find a better use case later in the guide where we actually get additional information on a problem a reader is facing? Or is this more about the syntax?
  • "The Dokka Gradle plugin cannot be resolved from the Gradle Plugin Portal as of v0.9.15" - We should ask Jetbrains to publish it there.
  • "Configure project coordinates to org.example:my-kotlin-library:0.0.1" - Should also annotate the version property.
  • Instead of have the almost exact same code in multiple subdirectories, I'd just include specific portions of a file from a single source code example: https://github.com/gradle-guides/building-kotlin-jvm-libraries/tree/master/samples/code. If you'd need to fix one example then you'll likely have to fix them all.
@bamboo

This comment has been minimized.

Show comment
Hide comment
@bamboo

bamboo Sep 11, 2017

Member

Great to see the Kotlin DSL there. A few comments:

  • import org.gradle.kotlin.dsl.* should not be necessary since all members in that package are already implicitly imported.
  • The desired Kotlin version should be specified in the kotlin dependency builder otherwise it will default to the embedded Kotlin version.
  • Maven repository specs can be abbreviated to maven(url = "$buildDir/repository") if you'd like.
Member

bamboo commented Sep 11, 2017

Great to see the Kotlin DSL there. A few comments:

  • import org.gradle.kotlin.dsl.* should not be necessary since all members in that package are already implicitly imported.
  • The desired Kotlin version should be specified in the kotlin dependency builder otherwise it will default to the embedded Kotlin version.
  • Maven repository specs can be abbreviated to maven(url = "$buildDir/repository") if you'd like.
@eriwen

This comment has been minimized.

Show comment
Hide comment
@eriwen

eriwen Sep 11, 2017

Member

Thank you everyone for you feedback. I have addressed it in gradle-guides/building-kotlin-jvm-libraries@ebc2cdb.

Inline responses:

@pioterj

I'd consider dropping "JVM" from the title. We don't have it for Java and Scala library guides.
Kotlin is unique in that in can compile to JS. We are likely to write a Building Kotlin for JS guides in the not-so-distant future. Full-stack baby!

@bmuschko

Other getting started guides do not spell out "step x". We should align.
In my mind, we need a visual indicator of the "meat" of all getting started guides in the TOC. I don't find the numbering as helpful as it could be (this is different for topical guides IMO), so the best I can figure is adding a "Step X:" prefix. I did this in the webpack guide as well.

"Create project directory" raises the question why there's no init task support like for other languages. I understand why but maybe spell it out to the reader. IMHO init should become a public API that lets you define your own definition. That could become part of the external Kotlin plugin.

I don't disagree, but I don't see this is a large motivation to pick up the story we have for this.

Listing that uses build-scan seems to have a rendering issue (marked green). Or was that intentional? I believe users will copy/paste that. This is the first time we do that in a guide

The green is intentional as part of the diff syntax, however, I've removed the "+" so folks copying won't have an issue.

"Digging deeper with a build scan". Apart from seeing that the Kotlin plugin was applied in a build scan I don't quite the benefit of having a full section on the build scan.

I note in the guide that it's important to know that the Kotlin plugin applies the Java plugin, which we can only figure out via a build scan, and that we'll be using configurations from the Java plugin later. This is why that is useful and important.

"The Dokka Gradle plugin cannot be resolved from the Gradle Plugin Portal as of v0.9.15" - We should ask Jetbrains to publish it there.

They publish it incorrectly, and there is a GitHub issue I commented on about it and voted on.

Instead of have the almost exact same code in multiple subdirectories, I'd just include specific portions of a file from a single source code example

I agree, and this is what I started with. I could not get the examples to look as I wanted with 1 project after much effort, so I found it more pragmatic to do search and replace.

@bamboo

Maven repository specs can be abbreviated to maven(url = "$buildDir/repository") if you'd like.

I started with this, but I think it's more important to have the example work for Gradle 4.1 then to show off the latest hotness.

Member

eriwen commented Sep 11, 2017

Thank you everyone for you feedback. I have addressed it in gradle-guides/building-kotlin-jvm-libraries@ebc2cdb.

Inline responses:

@pioterj

I'd consider dropping "JVM" from the title. We don't have it for Java and Scala library guides.
Kotlin is unique in that in can compile to JS. We are likely to write a Building Kotlin for JS guides in the not-so-distant future. Full-stack baby!

@bmuschko

Other getting started guides do not spell out "step x". We should align.
In my mind, we need a visual indicator of the "meat" of all getting started guides in the TOC. I don't find the numbering as helpful as it could be (this is different for topical guides IMO), so the best I can figure is adding a "Step X:" prefix. I did this in the webpack guide as well.

"Create project directory" raises the question why there's no init task support like for other languages. I understand why but maybe spell it out to the reader. IMHO init should become a public API that lets you define your own definition. That could become part of the external Kotlin plugin.

I don't disagree, but I don't see this is a large motivation to pick up the story we have for this.

Listing that uses build-scan seems to have a rendering issue (marked green). Or was that intentional? I believe users will copy/paste that. This is the first time we do that in a guide

The green is intentional as part of the diff syntax, however, I've removed the "+" so folks copying won't have an issue.

"Digging deeper with a build scan". Apart from seeing that the Kotlin plugin was applied in a build scan I don't quite the benefit of having a full section on the build scan.

I note in the guide that it's important to know that the Kotlin plugin applies the Java plugin, which we can only figure out via a build scan, and that we'll be using configurations from the Java plugin later. This is why that is useful and important.

"The Dokka Gradle plugin cannot be resolved from the Gradle Plugin Portal as of v0.9.15" - We should ask Jetbrains to publish it there.

They publish it incorrectly, and there is a GitHub issue I commented on about it and voted on.

Instead of have the almost exact same code in multiple subdirectories, I'd just include specific portions of a file from a single source code example

I agree, and this is what I started with. I could not get the examples to look as I wanted with 1 project after much effort, so I found it more pragmatic to do search and replace.

@bamboo

Maven repository specs can be abbreviated to maven(url = "$buildDir/repository") if you'd like.

I started with this, but I think it's more important to have the example work for Gradle 4.1 then to show off the latest hotness.

@pioterj

This comment has been minimized.

Show comment
Hide comment
@pioterj

pioterj Oct 6, 2017

Member

@eriwen Is it actually waiting for review? The guide is already published.

Member

pioterj commented Oct 6, 2017

@eriwen Is it actually waiting for review? The guide is already published.

@eriwen

This comment has been minimized.

Show comment
Hide comment
@eriwen

eriwen Oct 6, 2017

Member

@pioterj nah, I just never came back to close it. Thanks!

Member

eriwen commented Oct 6, 2017

@pioterj nah, I just never came back to close it. Thanks!

@eriwen eriwen closed this Oct 6, 2017

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