From 4391776b5d027a053084ddc99d7caf24edf9aa12 Mon Sep 17 00:00:00 2001
From: Hunter Mellema <124718352+hpmellema@users.noreply.github.com>
Date: Mon, 19 Feb 2024 09:58:48 -0700
Subject: [PATCH] Add gradle plugin migration guide (#2146)
Add Gradle plugin migration guide for moving from earlier version to v0.10.0+ of the gradle plugin.
---
.../gradle-plugin/gradle-migration-guide.rst | 186 ++++++++++++++++++
.../source-2.0/guides/gradle-plugin/index.rst | 12 +-
2 files changed, 196 insertions(+), 2 deletions(-)
create mode 100644 docs/source-2.0/guides/gradle-plugin/gradle-migration-guide.rst
diff --git a/docs/source-2.0/guides/gradle-plugin/gradle-migration-guide.rst b/docs/source-2.0/guides/gradle-plugin/gradle-migration-guide.rst
new file mode 100644
index 00000000000..293d7c6f420
--- /dev/null
+++ b/docs/source-2.0/guides/gradle-plugin/gradle-migration-guide.rst
@@ -0,0 +1,186 @@
+.. _gradle_migration_guide:
+
+==========================================
+Migrating to Gradle plugin version 0.10.0+
+==========================================
+
+This guide describes how to migrate your Gradle build files
+to use the `Smithy Gradle plugins`_ v0.10.0+ without breaking
+your existing Gradle projects.
+
+.. warning::
+ Versions 0.10.0+ of the Smithy Gradle plugins will automatically apply
+ the Smithy formatter to your Smithy source files. This can result in a
+ large number of formatting changes the first time you apply these plugins
+ to your project. For instructions on how to disable automatic formatting
+ see :ref:`Disabling the Smithy formatter <disable-smithy-formatter>`.
+
+Update plugin artifact
+======================
+
+The Smithy Gradle plugin has been broken up into separate capability
+(``smithy-jar``) and convention (``smithy-base``) plugins. The
+``smithy-jar`` plugin operates similarly to the previous ``smithy`` plugin,
+but no longer applies the ``java`` plugin automatically. To migrate to the
+new plugin, change the artifact id in the ``plugins`` block and apply the
+``java`` (or ``java-library``) plugin if it is not already applied to
+your project.
+
+.. tab:: Kotlin
+
+ .. code-block:: diff
+ :caption: build.gradle.kts
+
+ plugins {
+ - id("software.amazon.smithy").version("0.7.0")
+ + `java`
+ + id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0")
+ }
+
+.. tab:: Groovy
+
+ .. code-block:: diff
+ :caption: build.gradle
+
+ plugins {
+ - id 'software.amazon.smithy' version '0.7.0'
+ + id 'java'
+ + id 'software.amazon.smithy.gradle.smithy-jar' version '0.10.0'
+ }
+
+Remove Buildscript Dependencies
+===============================
+
+Pre-0.10.0 versions of the Smithy Gradle plugins use the buildscript block
+for build-only dependencies such as Smithy build plugins. The 0.10.0+
+Gradle plugins create a new Gradle `Configuration`_ ``smithyBuild``
+for these build-only dependencies.
+
+.. tab:: Kotlin
+
+ .. code-block:: diff
+ :caption: build.gradle.kts
+
+ -buildscript {
+ - repositories {
+ - mavenLocal()
+ - mavenCentral()
+ - }
+ -
+ - dependencies {
+ - // Dependency repeated here and below because model discovery previously
+ - // only ran on buildscript classpath for projections
+ - classpath("software.amazon.smithy:smithy-aws-traits:__smithy_version__")
+ - // Take a dependency on the internal model package. This
+ - // dependency *must* be a buildscript only dependency to ensure
+ - // that is does not appear in the generated JAR.
+ - classpath("com.foo.baz:foo-internal-model:1.0.0")
+ - }
+ -}
+
+ dependencies {
+ implementation("software.amazon.smithy:smithy-model:__smithy_version__")
+
+ implementation("software.amazon.smithy:smithy-aws-traits:__smithy_version__")
+ + smithyBuild("com.foo.baz:foo-internal-model:1.0.0")
+ }
+
+.. tab:: Groovy
+
+ .. code-block:: diff
+ :caption: build.gradle
+
+ -buildscript {
+ - repositories {
+ - mavenLocal()
+ - mavenCentral()
+ - }
+ -
+ - dependencies {
+ - // Dependency repeated here and below because model discovery previously
+ - // only ran on buildscript classpath for projections
+ - classpath 'software.amazon.smithy:smithy-aws-traits:__smithy_version__'
+ - // Take a dependency on the internal model package. This
+ - // dependency *must* be a buildscript only dependency to ensure
+ - // that is does not appear in the generated JAR.
+ - classpath 'com.foo.baz:foo-internal-model:1.0.0'
+ - }
+ -}
+
+ dependencies {
+ implementation 'software.amazon.smithy:smithy-model:__smithy_version__'
+
+ implementation 'software.amazon.smithy:smithy-aws-traits:__smithy_version__'
+ + smithyBuild 'com.foo.baz:foo-internal-model:1.0.0'
+ }
+
+Change ``projection`` property name
+===================================
+
+The property ``projection`` has also been updated to ``sourceProjection``.
+
+.. tab:: Kotlin
+
+ .. code-block:: diff
+ :caption: build.gradle.kts
+
+ -configure<software.amazon.smithy.gradle.SmithyExtension> {
+ +smithy {
+ - projection = "foo"
+ + sourceProjection.set("foo")
+ }
+
+.. tab:: Groovy
+
+ .. code-block:: diff
+ :caption: build.gradle
+
+ -configure<software.amazon.smithy.gradle.SmithyExtension> {
+ +smithy {
+ - projection = "foo"
+ + sourceProjection = "foo"
+ }
+
+Change ``smithyBuildJar`` task name
+===================================
+
+The ``smithyBuildJar`` task has been removed. Instead, the plugin now
+executes separate ``smithyBuild`` and ``smithyJarStaging`` tasks. If
+your project previously configured the ``smithyBuildJar``,
+configure the ``smithyBuild`` task instead. Tasks that depended on
+``smithyBuildJar`` should now depend on the ``jar`` task.
+
+.. tab:: Kotlin
+
+ .. code-block:: diff
+ :caption: build.gradle.kts
+
+ tasks {
+ - smithyBuildJar {
+ + smithyBuild {
+ smithyBuildConfigs.set(files("smithy-build.json", other))
+ }
+ // ..
+ }
+
+ -tasks["smithyBuildJar"].dependsOn("otherTask")
+ +tasks["jar"].dependsOn("otherTask")
+
+.. tab:: Groovy
+
+ .. code-block:: diff
+ :caption: build.gradle
+
+ tasks {
+ - smithyBuildJar {
+ + smithyBuild {
+ smithyBuildConfigs = files("smithy-build.json", other)
+ }
+ // ..
+ }
+
+ -tasks["smithyBuildJar"].dependsOn("otherTask")
+ +tasks["jar"].dependsOn("otherTask")
+
+.. _Smithy Gradle plugins: https://github.com/awslabs/smithy-gradle-plugin/
+.. _Configuration: https://docs.gradle.org/current/dsl/org.gradle.api.artifacts.Configuration.html
diff --git a/docs/source-2.0/guides/gradle-plugin/index.rst b/docs/source-2.0/guides/gradle-plugin/index.rst
index 5aec6b21684..4139418b242 100644
--- a/docs/source-2.0/guides/gradle-plugin/index.rst
+++ b/docs/source-2.0/guides/gradle-plugin/index.rst
@@ -8,6 +8,12 @@ The `Smithy Gradle plugins`_ integrate Smithy with the `Gradle`_ build system. T
build artifacts from Smithy models, and generate JARs for Smithy models and model
:ref:`projections <projections>`.
+.. toctree::
+ :maxdepth: 1
+ :caption: Migrate to version 0.8.0+
+
+ gradle-migration-guide
+
Plugins
=======
@@ -151,6 +157,8 @@ Runtime dependencies can be added directly to the ``runtimeClasspath`` configura
or to a configuration that extends ``runtimeClasspath``, such as the ``implementation``
configuration added by the ``java-library`` plugin.
+.. _dependencies:
+
Build Dependencies
^^^^^^^^^^^^^^^^^^
@@ -256,8 +264,6 @@ This extension supports the following properties:
- ``Directory``
- Defines where Smithy build artifacts are written.
-.. _dependencies:
-
Customize output directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -382,6 +388,8 @@ process if necessary. To run Smithy CLI commands in a process set the
fork = true
}
+.. _disable-smithy-formatter:
+
Disable Smithy Formatter
^^^^^^^^^^^^^^^^^^^^^^^^