Implement release plugin (#41)

Per [b/317081045](https://b.corp.google.com/issues/317081045),

This implements a new plugin for preparing a release. This plugin
provides functionality to;

- Update the project version declared in the `gradle.properties` file
- Create a new `.api` file in the *new* `api` directory
- Automatically generate the release notes

This PR also fixes the following:

- [b/319482236](https://b.corp.google.com/issues/319482236) -> Store
released `.api` files in a `api` directory

> [!WARNING]
>
> This PR should not be merged until the following is complete:
>
> - [x] The branch is not currently in a release state
> - [x] All of the previous release's `.api` files are present in the
`api` directory

---------

Co-authored-by: Rodrigo Lazo <[email protected]>

.github/workflows/check_for_api_changes.yml

@@ -18,12 +18,12 @@ jobs:
           distribution: temurin
           cache: gradle
 
-      - name: Update released.api
+      - name: Generate the api file
         run: |
-          ./gradlew updateApi --no-daemon
+          ./gradlew generativeai:exportApi --no-daemon
 
-      - name: Save released.api from master
-        run: mv generativeai/released.api ~/released.api
+      - name: Save public.api from master
+        run: mv generativeai/public.api ~/public.api
 
       - name: Checkout branch
         uses: actions/[email protected]
@@ -36,11 +36,11 @@ jobs:
           cache: gradle
 
       - name: Copy saved api to branch
-        run: mv ~/released.api generativeai/released.api
+        run: mv ~/public.api generativeai/public.api
 
       - name: Run api warning task
         run: |
-          ./gradlew warnAboutApiChanges --no-daemon
+          ./gradlew generativeai:warnAboutApiChanges --no-daemon
 
       - name: Add PR Comment
         if: ${{ hashFiles('api_changes.md') != '' }}

generativeai/released.api → api/0.1.2.api

@@ -287,4 +287,3 @@ public final class com/google/ai/client/generativeai/type/UnknownException : com
 	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
 	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 }
-

generativeai/build.gradle.kts

@@ -20,6 +20,7 @@ plugins {
     id("org.jetbrains.dokka")
     id("com.ncorti.ktfmt.gradle")
     id("changelog-plugin")
+    id("release-plugin")
     kotlin("android")
     kotlin("plugin.serialization")
 }

plugins/README.md

@@ -5,26 +5,26 @@ number of monotonous tasks. You can read more on these plugins and the tasks the
 
 ## ChangelogPlugin
 
-Creates and manages changelog files. These files are used to signify changes made to the repo that
+Creates and manages changelog files. These files are used to signify changes made to the repo that 
 should invoke a release, alongside text to display in the release notes at release time.
 
-Change files are (by default) created under the `.changes` directory at the root of the repo.
+Change files are (by default) created under the `.changes` directory at the root of the repo. 
 These files are json encoded variants of a [Changelog](./src/main/java/com/google/gradle/types/Changelog.kt) instance- 
 which is just an organization of what impact the change had (will it invoke a patch, minor, or 
 major bump?) and an (optional) end-user readable message to show alongside the other changes at 
 release time. By default, the files are saved as a random sequence of four words (to avoid 
 collisions).
 
-During a release cycle, the `.changes` directory will be filled with change files. When it comes to
-release time, these changes will be combined into a single `release_notes.md` file that contains
-all the changes made- in a consumable format. After a release, the `.changes` directory will be
+During a release cycle, the `.changes` directory will be filled with change files. When it comes to 
+release time, these changes will be combined into a single `release_notes.md` file that contains 
+all the changes made- in a consumable format. After a release, the `.changes` directory will be 
 wiped, and the cycle will continue.
 
 To assist in this endeavour, the ChangelogPlugin registers an internal plugin and a few tasks:
 
 ### APIPlugin
 
-An internal plugin (automatically added, and cannot be explicitly applied) that facilitates the
+An internal plugin (automatically added, and cannot be explicitly applied) that facilitates the 
 generation of `.api` files.
 
 #### Tasks
@@ -33,8 +33,8 @@ The APIPlugin registers the two following tasks to facilitate this process:
 
 - [buildApi](./src/main/java/com/google/gradle/plugins/ApiPlugin.kt) -> Creates a `.api` file 
 containing the public API of the project.
-- [updateApi](./src/main/java/com/google/gradle/plugins/ApiPlugin.kt) -> Updates (or creates) the 
-`released.api` file at the project directory; keeping track of the currently released/public api. 
+- [exportApi](./src/main/java/com/google/gradle/plugins/ApiPlugin.kt) -> Exports the `.api` file 
+generated by the `buildApi` task to a file at the project directory named `public.api`.
 
 ### Tasks
 
@@ -72,3 +72,22 @@ The LicensePlugin registers the two following tasks to facilitate this process:
 a license header in present in a set of files.
 - [ApplyLicenseTask](./src/main/java/com/google/gradle/tasks/ApplyLicenseTask.kt) -> Applies a 
 license header to a set of files.
+
+## ReleasePlugin
+
+Facilitates the procedures expected to be done during a release. 
+While the `publishAllPublicationsToMavenRepository` task is used to actually *generate* the release 
+artifact, this plugin registers tasks that should be ran *before* the release artifact is generated. 
+Effectively "preparing" the project to be released.
+
+### Tasks
+
+The ReleasePlugin registers the three following tasks:
+
+- [updateVersion](./src/main/java/com/google/gradle/tasks/VersionBumpTask.kt) -> Updates the project 
+version declared in the `gradle.properties` file to reflect the version generated by the release 
+notes.
+- [createNewApiFile](./src/main/java/com/google/gradle/plugins/ReleasePlugin.kt) -> Creates a new 
+`.api` file in the root `api` directory; aligning with the current state of the public api.
+- [prepareRelease](./src/main/java/com/google/gradle/plugins/ReleasePlugin.kt) -> Does everything 
+needed to prepare a release; creates the release notes and runs the above tasks.

plugins/build.gradle.kts

@@ -45,6 +45,10 @@ gradlePlugin {
             id = "changelog-plugin"
             implementationClass = "com.google.gradle.plugins.ChangelogPlugin"
         }
+        register("release-plugin") {
+            id = "release-plugin"
+            implementationClass = "com.google.gradle.plugins.ReleasePlugin"
+        }
     }
 }
 

plugins/src/main/java/com/google/gradle/plugins/ApiPlugin.kt

@@ -16,7 +16,9 @@
 
 package com.google.gradle.plugins
 
+import com.google.gradle.tasks.CopyFileTask
 import com.google.gradle.util.android
+import com.google.gradle.util.outputFile
 import com.google.gradle.util.release
 import com.google.gradle.util.tempFile
 import java.io.File
@@ -29,41 +31,35 @@ import org.gradle.api.tasks.Optional
 import org.gradle.kotlin.dsl.create
 import org.gradle.kotlin.dsl.register
 
+typealias BuildApiTask = KotlinApiBuildTask
+
 /**
  * A Gradle plugin for creating `.api` files; representing the public API of the project.
  *
- * By default, a `released.api` file (at the root of the project) will be used as a base for the
- * released api.
- *
  * Registers two tasks:
  * - `buildApi` -> creates a `.api` file containing the *current* public API of the project.
- * - `updateApi` -> updates the `released.api` file at the project root to match the one generated by
- *   `buildApi`; effectively saying that the released api is up to date with the current repo state.
+ * - `exportApi` -> exports the file generated by `buildApi` to a `public.api` file at the project
+ *   directory
  *
  * @see ApiPluginExtension
  * @see ChangelogPluginExtension
  */
 abstract class ApiPlugin : Plugin<Project> {
   override fun apply(project: Project) {
     with(project) {
-      val extension = extensions.create<ApiPluginExtension>("api").apply { commonConfiguration() }
+      extensions.create<ApiPluginExtension>("api").apply { commonConfiguration() }
 
       val buildApi = registerBuildApiTask()
 
-      tasks.register<Copy>("updateApi") {
-        val fileName = extension.apiFile.map { it.name }
-        val filePath = extension.apiFile.map { it.parent }
-
-        from(buildApi)
-        into(filePath)
-
-        rename { fileName.get() }
+      tasks.register<CopyFileTask>("exportApi") {
+        source.set(buildApi.outputFile)
+        dest.set(project.file("public.api"))
       }
     }
   }
 
   private fun Project.registerBuildApiTask() =
-    tasks.register<KotlinApiBuildTask>("buildApi") {
+    tasks.register<BuildApiTask>("buildApi") {
       val classes = provider { android.release.output.classesDirs }
 
       inputClassesDirs = files(classes)
@@ -73,14 +69,16 @@ abstract class ApiPlugin : Plugin<Project> {
 
   context(Project)
   private fun ApiPluginExtension.commonConfiguration() {
-    apiFile.convention(file("released.api"))
+    val latestApiFile = project.file("api/${project.version}.api")
+
+    apiFile.convention(latestApiFile)
   }
 }
 
 /**
  * Extension properties for the [ApiPlugin].
  *
- * @property apiFile The file to reference as (and save to) in regards to the publicly released api.
+ * @property apiFile The file to reference to for the publicly released api.
  */
 abstract class ApiPluginExtension {
   @get:Optional abstract val apiFile: Property<File>

plugins/src/main/java/com/google/gradle/plugins/ChangelogPlugin.kt

@@ -21,11 +21,12 @@ import com.google.gradle.tasks.MakeChangeTask
 import com.google.gradle.tasks.MakeReleaseNotesTask
 import com.google.gradle.tasks.WarnAboutApiChangesTask
 import com.google.gradle.types.Changelog
-import com.google.gradle.types.ModuleVersion
 import com.google.gradle.types.RandomWordsGenerator
 import com.google.gradle.util.apply
 import com.google.gradle.util.buildDir
 import com.google.gradle.util.childFile
+import com.google.gradle.util.moduleVersion
+import com.google.gradle.util.orElseIfNotExists
 import com.google.gradle.util.outputFile
 import com.google.gradle.util.provideProperty
 import com.google.gradle.util.tempFile
@@ -69,7 +70,9 @@ abstract class ChangelogPlugin : Plugin<Project> {
     with(project) {
       val extension =
         extensions.create<ChangelogPluginExtension>("changelog").apply { commonConfiguration() }
-      val releasedApiFile = apiPlugin.apiFile
+
+      val exportedApiFile = provider { file("public.api") }
+      val releasedApiFile = exportedApiFile.orElseIfNotExists(apiPlugin.apiFile)
       val newApiFile = tasks.named("buildApi").outputFile
 
       val findChanges =
@@ -108,8 +111,9 @@ abstract class ChangelogPlugin : Plugin<Project> {
 
       tasks.register<MakeReleaseNotesTask>("makeReleaseNotes") {
         onlyIf("No changelog files found") { changelogFiles.get().isNotEmpty() }
+
         changeFiles.set(changelogFiles)
-        version.set(ModuleVersion.fromStringOrNull(project.version.toString()))
+        version.set(project.moduleVersion)
         outputFile.set(rootProject.buildDir("release_notes.md"))
 
         finalizedBy(deleteChangeFiles)

plugins/src/main/java/com/google/gradle/plugins/ReleasePlugin.kt

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.gradle.plugins
+
+import com.google.gradle.tasks.CopyFileTask
+import com.google.gradle.tasks.MakeReleaseNotesTask
+import com.google.gradle.tasks.VersionBumpTask
+import com.google.gradle.types.ModuleVersion
+import com.google.gradle.util.moduleVersion
+import com.google.gradle.util.outputFile
+import com.google.gradle.util.readFirstLine
+import java.io.File
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.named
+import org.gradle.kotlin.dsl.provideDelegate
+import org.gradle.kotlin.dsl.register
+
+/**
+ * A Gradle plugin for preparing a release.
+ *
+ * Intended to be ran before running `publishAllPublicationsToMavenRepository`.
+ *
+ * Registers three tasks:
+ * - `updateVersion` -> updates the project version declared in `gradle.properties` file, according
+ *   to the release notes.
+ * - `createNewApiFile` -> creates a new `.api` file in the `api` directory for the release,
+ *   aligning with the current state of the public api; for future auditing.
+ * - `prepareRelease` -> does everything needed to prepare a release; creates the release notes and
+ *   runs the above tasks.
+ *
+ * If any of these tasks are ran without changelog files present, the current version declared in
+ * the `gradle.properties` file will be used instead.
+ *
+ * @see ApiPluginExtension
+ * @see ChangelogPluginExtension
+ */
+abstract class ReleasePlugin : Plugin<Project> {
+  override fun apply(project: Project) {
+    with(project) {
+      val buildApi = tasks.named<BuildApiTask>("buildApi")
+      val makeReleaseNotes = tasks.named<MakeReleaseNotesTask>("makeReleaseNotes")
+
+      val releaseNotes = makeReleaseNotes.outputFile
+      val releasingVersion =
+        releaseNotes.map { parseReleaseVersion(it) }.orElse(project.moduleVersion)
+
+      val updateVersion =
+        tasks.register<VersionBumpTask>("updateVersion") { newVersion.set(releasingVersion) }
+
+      val createNewApiFile =
+        tasks.register<CopyFileTask>("createNewApiFile") {
+          val newApiFile = releasingVersion.map { rootProject.file("api/$it.api") }
+
+          source.set(buildApi.outputFile)
+          dest.set(newApiFile)
+        }
+
+      tasks.register("prepareRelease") {
+        group = "publishing"
+
+        dependsOn(makeReleaseNotes, updateVersion, createNewApiFile)
+      }
+    }
+  }
+
+  private fun parseReleaseVersion(releaseNotes: File): ModuleVersion {
+    val version = releaseNotes.readFirstLine().substringAfter("#").trim()
+
+    return ModuleVersion.fromStringOrNull(version)
+      ?: throw RuntimeException("Invalid release notes version found")
+  }
+}

plugins/src/main/java/com/google/gradle/tasks/CopyFileTask.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.gradle.tasks
+
+import java.io.File
+import org.gradle.api.DefaultTask
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Copy
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.TaskAction
+
+/**
+ * Copies a file (or directory) from one place to another.
+ *
+ * An alternative to the standard [Copy] task provided by gradle; that allows better interop with
+ * providers, caching, directories, and individual files.
+ *
+ * If the file is a directory, all of its contents will be copied alongside it.
+ *
+ * ***If there is already a file or directory present at the destination, its contents will be
+ * overwritten.***
+ *
+ * @property source the file or directory to copy from
+ * @property dest where to copy the file or directory to
+ */
+abstract class CopyFileTask : DefaultTask() {
+  @get:InputFile abstract val source: Property<File>
+
+  @get:OutputFile abstract val dest: Property<File>
+
+  @TaskAction
+  fun create() {
+    source.get().copyRecursively(dest.get(), overwrite = true)
+  }
+}