Add Migration Example Docs #178

tresat · 2025-03-06T19:51:02Z

No description provided.

docs/ROADMAP.md

big-guy · 2025-03-06T21:11:49Z

docs/ROADMAP.md

@@ -11,7 +11,7 @@ Below, you can see the key milestones we anticipate.
 | ----------------------------------- |:-:| ------------: |
 | First Early Access Preview (EAP)    | ✅ |     July 2024 |
 | Second Early Access Preview (EAP 2) | ✅ | November 2024 |
-| Third Early Access Preview (EAP 3)  | 🏗️ | February 2025 |
+| Third Early Access Preview (EAP 3)  | 🏗️ |    March 2025 |


big-guy · 2025-03-06T21:14:15Z

docs/reference/migrating-example.md

+```
+pluginManagement {
+    repositories {
+        gradlePluginPortal()


This is the default?

What do you mean? Removing this from the included declarative-logic build in the Gradle Client breaks that build.

In this place it is the settings file for the outer build, me thinks. Then it's not necessary here,

💭 It would be good to have the path of the file for each snippet to make navigating the snippets easier.

docs/reference/migrating-example.md

big-guy · 2025-03-06T21:16:38Z

docs/reference/migrating-example.md

+```
+
+And we _removed_ these dependencies from the `jvmMain.dependencies` block where they were previously declared.
+Set the org.gradle.kotlin.dsl.dcl flag in the project's properties file.


This looks out of place?

I'll edit to make it stand out more. It is needed as part of this step, else Software Types won't work in KTS files.

I think this should be part of the "initial setup"

big-guy · 2025-03-06T21:17:42Z

docs/reference/migrating-example.md

+}
+```
+
+And we _removed_ these dependencies from the `jvmMain.dependencies` block where they were previously declared.


What's unclear here is if this is equivalent or if we've changed the meaning of these dependencies.

I think because Gradle Client was only targeting the JVM and the kotlinApplication software type only works with JVM, this is the same.

Good idea, I'll go into more detail here.

big-guy · 2025-03-06T21:18:05Z

docs/reference/migrating-example.md

+
+This represents the minimal configuration needed to make use of this `kotlinApplication` Software Type - which is why this snippet also declares the required JDK version information.
+
+Continue to do this for each of your dependencies.


To do what?

Will expand.

eskatos · 2025-03-07T06:51:14Z

docs/reference/README.md

@@ -2,4 +2,5 @@

 * [`gradle init`](./build-init.md) - generate new builds using software types and DCL files
 * [Software Features](./software-features.md) - configuration model used by software developers
+* [Example Project Migration](./migrating-example.md) - notes on the migration of an actual Gradle KMP build to DCL


❌ I would not call it KMP, it is not multiplatform, it only targets the JVM.

Suggested change

* [Example Project Migration](./migrating-example.md) - notes on the migration of an actual Gradle KMP build to DCL

* [Example Project Migration](./migrating-example.md) - notes on the migration of an existing Gradle build for a Kotlin Compose for Desktop Application to DCL

eskatos · 2025-03-07T06:52:56Z

docs/reference/migrating-example.md

@@ -0,0 +1,171 @@
+# Example Migration
+
+In Feb/March 2025, using the version of Declarative Gradle that would be made available as EAP 3, we migrated the [`gradle client`](https://github.com/gradle/gradle-client) to using DCL build files and a custom Software Type that described the tools and features used by this particular build.


💭 It might be good to quickly explain what the "gradle-client" is here. A single sentence should be enough.

eskatos · 2025-03-07T06:57:12Z

docs/reference/migrating-example.md

+Gradle has always supported mixing build script DSLs between projects in a multi-project build using Groovy and Kotlin DSLs.
+It continues to support doing the same with DCL buildscripts, which allows us to migrate project by project.
+
+# Migration Process for Gradle-Client


🤔 I would make this two parts. First a short section about the overall migration process and then a more detailed one about how it was applied to gradle-client. My thinking is that the former section would help readers get an idea of the overall process and refer to it as a kind of reference after having read the rest.

eskatos · 2025-03-07T06:58:30Z

docs/reference/migrating-example.md

+
+Features are constantly being added to the Declarative Gradle support.  
+Any project interested in experimenting with DCL files should ensure they are using at least the latest stable Gradle release.
+For the migration of the Gradle-Client project, we upgraded the wrapper to use a nightly Gradle build [gradle-8.14-20250222002553+0000](https\://services.gradle.org/distributions-snapshots/gradle-8.14-20250222002553+0000-bin.zip) in order to get support for the very latest Declarative Gradle features.


❌ We should use a published version here, a milestone would be good.

eskatos · 2025-03-07T07:03:11Z

docs/reference/migrating-example.md

+We decided to start with the [`gradle-client` subproject](https://github.com/gradle/gradle-client/tree/main/gradle-client), as this was the most important and fully featured project contained in the Gradle Client build, which would be the most interesting to investigate.
+For your own migrations, you should probably consider which projects would be _simplest_ to migrate.
+Projects that are simpler and most similar to our declarative samples are good candidates.
+If your project _doesn't_ already use Gradle's Kotlin DSL, you'll want to migrate to this first from your Groovy build using the existing [migration guide](https://docs.gradle.org/current/userguide/migrating_from_groovy_to_kotlin_dsl.html) in the Gradle documentation.


❌ I would explain this in the reverse order. I think we should explain the simplest first. Identify the projects for which an existing prototype software type already exists, vs. the ones for which they will have to write a custom one. This is a good opportunity to explain the current lack of composability and teach users how to navigate this current limitation. Then migrate the easy ones first in order to make progress quickly and get accustomed to DCL idioms before diving. Later one come back to the complex projects and introduce custom software type(s).

eskatos · 2025-03-07T07:04:22Z

docs/reference/migrating-example.md

+```
+pluginManagement {
+    repositories {
+        gradlePluginPortal()


In this place it is the settings file for the outer build, me thinks. Then it's not necessary here,

💭 It would be good to have the path of the file for each snippet to make navigating the snippets easier.

eskatos · 2025-03-07T07:05:19Z

docs/reference/migrating-example.md

+```
+
+And we _removed_ these dependencies from the `jvmMain.dependencies` block where they were previously declared.
+Set the org.gradle.kotlin.dsl.dcl flag in the project's properties file.


I think this should be part of the "initial setup"

tresat added 4 commits March 6, 2025 09:35

Update prototype version in build init docs

6a240d5

Update EAP 3 expected date

81cfabe

Add example project migration initial draft/outline

ed6d87d

Add note on using VCs in roadmap

dc9554e

tresat self-assigned this Mar 6, 2025

big-guy requested changes Mar 6, 2025

View reviewed changes

eskatos requested changes Mar 7, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Migration Example Docs #178

Add Migration Example Docs #178

tresat commented Mar 6, 2025

big-guy Mar 6, 2025

big-guy Mar 6, 2025

tresat Mar 6, 2025

eskatos Mar 7, 2025

big-guy Mar 6, 2025

tresat Mar 6, 2025

eskatos Mar 7, 2025

big-guy Mar 6, 2025

tresat Mar 6, 2025

big-guy Mar 6, 2025

tresat Mar 6, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025

eskatos Mar 7, 2025


		This represents the minimal configuration needed to make use of this `kotlinApplication` Software Type - which is why this snippet also declares the required JDK version information.

		Continue to do this for each of your dependencies.

	* [Example Project Migration](./migrating-example.md) - notes on the migration of an actual Gradle KMP build to DCL
	* [Example Project Migration](./migrating-example.md) - notes on the migration of an existing Gradle build for a Kotlin Compose for Desktop Application to DCL

		@@ -0,0 +1,171 @@
		# Example Migration

		In Feb/March 2025, using the version of Declarative Gradle that would be made available as EAP 3, we migrated the [`gradle client`](https://github.com/gradle/gradle-client) to using DCL build files and a custom Software Type that described the tools and features used by this particular build.

Add Migration Example Docs #178

Are you sure you want to change the base?

Add Migration Example Docs #178

Conversation

tresat commented Mar 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment