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

Documentation #106

Open
bamboo opened this Issue Jul 28, 2016 · 8 comments

Comments

Projects
None yet
6 participants
@bamboo
Member

bamboo commented Jul 28, 2016

Provide documentation in a suitable format for integration with the Gradle distribution about:

  1. Groovy/Kotlin interoperability
  2. Resources for the version of Kotlin being used
  3. DSL reference guide
  4. Current limitations (can I use Kotlin in buildSrc?)
  5. Known problems
@aesteve

This comment has been minimized.

Show comment
Hide comment
@aesteve

aesteve Aug 16, 2016

Hi, and thanks for the issue, this would definitely be a major feature.

Currently I have absolutely no clue where to find some documentation, and feel completely lost.

  1. IntelliJ, even with your plugin installation instructions (in this repo), doesn't open my project as a Gradle project. It has no idea it's a Gradle project since no build.gradle exists (even after restarting IntelliJ twice and even though settings.gradle has rootProject.buildFileName=build.gradle.kts
  2. Very trivial DSL use-case : maven { url 'my maven repo' } : what should I write instead ? maven { url("my repo") } displays a huge stacktrace ending with no resolved call

What should I do while waiting for this issue to be resolved ? There must be something I'm missing if Kotlin support is now the "default" for Gradle, there must a documentation somewhere ?

Back to Groovy in the meantime, at least I'm following this issue and will be updated :)

Thanks a lot for your work ! Hope there are simple answers to my questions. Thanks.

aesteve commented Aug 16, 2016

Hi, and thanks for the issue, this would definitely be a major feature.

Currently I have absolutely no clue where to find some documentation, and feel completely lost.

  1. IntelliJ, even with your plugin installation instructions (in this repo), doesn't open my project as a Gradle project. It has no idea it's a Gradle project since no build.gradle exists (even after restarting IntelliJ twice and even though settings.gradle has rootProject.buildFileName=build.gradle.kts
  2. Very trivial DSL use-case : maven { url 'my maven repo' } : what should I write instead ? maven { url("my repo") } displays a huge stacktrace ending with no resolved call

What should I do while waiting for this issue to be resolved ? There must be something I'm missing if Kotlin support is now the "default" for Gradle, there must a documentation somewhere ?

Back to Groovy in the meantime, at least I'm following this issue and will be updated :)

Thanks a lot for your work ! Hope there are simple answers to my questions. Thanks.

@bamboo

This comment has been minimized.

Show comment
Hide comment
@bamboo

bamboo Aug 16, 2016

Member

Hi @aesteve.

About your first question, when importing the project into IDEA point it to the settings.gradle file, that should make IDEA recognise it as Gradle project.

After that, with proper IDEA support, code assistance should aid you in answering your second question, inside the maven { } block type this. to see a list of maven specific configuration options. You should end up with something like maven { setUrl("my repo") } (the this qualifier is optional). There are a few differences between how things look in Kotlin and how they look in Groovy. We are working on minimising the differences wherever it makes sense to leverage familiarity and we'll be documenting the ones that remain before our 1.0 release. In the meanwhile please join us in the #gradle Kotlin Slack channel.

For clarification, as mentioned in the Gradle 3.0 Release Announcement:

Groovy is still the primary build language for Gradle scripts and will always be supported, but we are working intensely to make Gradle Script Kotlin fully production ready by the end of the year in order to provide the best possible development experience to Gradle users.

Thanks for your comments!

Member

bamboo commented Aug 16, 2016

Hi @aesteve.

About your first question, when importing the project into IDEA point it to the settings.gradle file, that should make IDEA recognise it as Gradle project.

After that, with proper IDEA support, code assistance should aid you in answering your second question, inside the maven { } block type this. to see a list of maven specific configuration options. You should end up with something like maven { setUrl("my repo") } (the this qualifier is optional). There are a few differences between how things look in Kotlin and how they look in Groovy. We are working on minimising the differences wherever it makes sense to leverage familiarity and we'll be documenting the ones that remain before our 1.0 release. In the meanwhile please join us in the #gradle Kotlin Slack channel.

For clarification, as mentioned in the Gradle 3.0 Release Announcement:

Groovy is still the primary build language for Gradle scripts and will always be supported, but we are working intensely to make Gradle Script Kotlin fully production ready by the end of the year in order to provide the best possible development experience to Gradle users.

Thanks for your comments!

@aesteve

This comment has been minimized.

Show comment
Hide comment
@aesteve

aesteve Aug 16, 2016

Thanks a lot for your answers ! I'll wait for 1.0 release then :)

aesteve commented Aug 16, 2016

Thanks a lot for your answers ! I'll wait for 1.0 release then :)

@flstaats

This comment has been minimized.

Show comment
Hide comment
@flstaats

flstaats Oct 27, 2016

I would like to see clear documentation on what the Kotlin specific idioms for writing plugins should be. One of the things that was missing in the early Gradle with Groovy documentation was clear guidance on preferred form, format and structure for plugins. In the early days you couldn't really create useful plugins without using undocumented features and API which were constantly changing. As a result the ecosystem has many wildly varying approaches to writing plugins and existing plugins haves supportability issues.

With Kotlin based plugins and a more mature Gradle infrastructure it would be great to provide templates and examples of the "preferred" plugin architecture and Kotlin coding style. This way people can be guided into a pit of success rather than wandering around in the dark undocumented forest.

flstaats commented Oct 27, 2016

I would like to see clear documentation on what the Kotlin specific idioms for writing plugins should be. One of the things that was missing in the early Gradle with Groovy documentation was clear guidance on preferred form, format and structure for plugins. In the early days you couldn't really create useful plugins without using undocumented features and API which were constantly changing. As a result the ecosystem has many wildly varying approaches to writing plugins and existing plugins haves supportability issues.

With Kotlin based plugins and a more mature Gradle infrastructure it would be great to provide templates and examples of the "preferred" plugin architecture and Kotlin coding style. This way people can be guided into a pit of success rather than wandering around in the dark undocumented forest.

@bamboo

This comment has been minimized.

Show comment
Hide comment
@bamboo

bamboo Oct 28, 2016

Member

Thanks for the feedback, @flstaats!

Member

bamboo commented Oct 28, 2016

Thanks for the feedback, @flstaats!

@bamboo bamboo changed the title from Improve documentation to User Manual Jan 5, 2017

@bamboo bamboo changed the title from User Manual to User Guide Feb 23, 2017

@eskatos eskatos changed the title from User Guide to Documentation Jan 19, 2018

@cvmocanu

This comment has been minimized.

Show comment
Hide comment
@cvmocanu

cvmocanu Mar 30, 2018

Do you have any ETA for documentation on Kotlin DSL?

We need at least a few tips on how to translate from Groovy DSL to Kotlin DSL.

As it stands, it's almost impossible for a noob like me to use KTS (as much as I would like to), since:

  • the documentation is in Groovy format EVERYWHERE (gradle website, stack overflow, etc.)
  • it's not even close to obvious how to translate from Gradle to Groovy

In my opinion, this should be considered as more important than probably any other feature (except critical bugs), since it prevents early adoption, and thus early feedback.

cvmocanu commented Mar 30, 2018

Do you have any ETA for documentation on Kotlin DSL?

We need at least a few tips on how to translate from Groovy DSL to Kotlin DSL.

As it stands, it's almost impossible for a noob like me to use KTS (as much as I would like to), since:

  • the documentation is in Groovy format EVERYWHERE (gradle website, stack overflow, etc.)
  • it's not even close to obvious how to translate from Gradle to Groovy

In my opinion, this should be considered as more important than probably any other feature (except critical bugs), since it prevents early adoption, and thus early feedback.

@JLLeitschuh

This comment has been minimized.

Show comment
Hide comment
@JLLeitschuh

JLLeitschuh Mar 30, 2018

Contributor

I basically gained all of my knowledge by reading the various samples that exist and pegging questions into the Gradle chat in the Kotlin Slack. Come by! Say hi!

I agree that there needs to be documentation added.

Perhaps @eriwen could provide some insight into the timelines on that?

Contributor

JLLeitschuh commented Mar 30, 2018

I basically gained all of my knowledge by reading the various samples that exist and pegging questions into the Gradle chat in the Kotlin Slack. Come by! Say hi!

I agree that there needs to be documentation added.

Perhaps @eriwen could provide some insight into the timelines on that?

@eriwen

This comment has been minimized.

Show comment
Hide comment
@eriwen

eriwen Apr 2, 2018

Member

I can say that Kotlin DSL 1.0 will not happen without an extensive amount of documentation to help users adopt it. Failing to provide this would be the fastest way to kill such a tremendous launch, and we will delay 1.0 until we have at least:

  • An authoritative migration guide from Groovy => Kotlin
  • A majority of Gradle docs showing Kotlin DSL configuration

I think the biggest reason this has not happened yet is that we are optimizing for soonest Kotlin DSL 1.0, and we want to avoid the overhead of changing documentation in the face of breaking DSL changes. I think I and the @gradle/kotlin-dsl team do owe you folks some kind of timeline soon, and I think we ought to meet about it ASAP.

Member

eriwen commented Apr 2, 2018

I can say that Kotlin DSL 1.0 will not happen without an extensive amount of documentation to help users adopt it. Failing to provide this would be the fastest way to kill such a tremendous launch, and we will delay 1.0 until we have at least:

  • An authoritative migration guide from Groovy => Kotlin
  • A majority of Gradle docs showing Kotlin DSL configuration

I think the biggest reason this has not happened yet is that we are optimizing for soonest Kotlin DSL 1.0, and we want to avoid the overhead of changing documentation in the face of breaking DSL changes. I think I and the @gradle/kotlin-dsl team do owe you folks some kind of timeline soon, and I think we ought to meet about it ASAP.

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