From a8a79fd1891c89b32809b2b723ced85d46965f3e 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 `. + +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 { + +smithy { + - projection = "foo" + + sourceProjection.set("foo") + } + +.. tab:: Groovy + + .. code-block:: diff + :caption: build.gradle + + -configure { + +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 `. +.. 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 ^^^^^^^^^^^^^^^^^^^^^^^^