1.5.5: Tagged internal APIs

changes/1.5.4.md

@@ -1,4 +1,4 @@
-# Gradle Plugins 1.5.3
+# Gradle Plugins 1.5.4
 
 This version includes a small change for the KordEx plugin.
 

changes/1.5.5.md

@@ -0,0 +1,5 @@
+# Gradle Plugins 1.5.5
+
+This version includes a small internal API change in the KordEx plugin.
+
+You shouldn't use internal APIs unless you need to, so I don't document them. This version adds an opt-in annotation to explicitly tag internal APIs.

gradle.properties

@@ -3,4 +3,4 @@ kotlin.incremental=true
 org.gradle.jvmargs=-XX:MaxMetaspaceSize=1024m
 org.gradle.parallel=true
 
-projectVersion=1.5.4
+projectVersion=1.5.5

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/InternalAPI.kt

@@ -0,0 +1,24 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+package dev.kordex.gradle.plugins.kordex
+
+@RequiresOptIn(
+	level = RequiresOptIn.Level.ERROR,
+	message = "This API is internal and should be avoided if possible, as it could be removed or changed without " +
+		"notice."
+)
+@Target(
+	AnnotationTarget.CLASS,
+	AnnotationTarget.TYPEALIAS,
+	AnnotationTarget.FUNCTION,
+	AnnotationTarget.PROPERTY,
+	AnnotationTarget.FIELD,
+	AnnotationTarget.CONSTRUCTOR,
+	AnnotationTarget.PROPERTY_SETTER,
+	AnnotationTarget.PROPERTY_SETTER
+)
+annotation class InternalAPI

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/KordExPlugin.kt

@@ -5,6 +5,7 @@
  */
 
 @file:Suppress("StringLiteralDuplication")
+@file:OptIn(InternalAPI::class)
 
 package dev.kordex.gradle.plugins.kordex
 
@@ -146,7 +147,7 @@ class KordExPlugin @Inject constructor(
 					)
 				}
 
-				I18nHelper.apply(target, extension)
+				I18nHelper.apply(target, extension.i18n)
 			}
 
 			if (extension.hasPlugin) {

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/_Properties.kt

@@ -10,20 +10,26 @@ import org.gradle.api.internal.provider.PropertyFactory
 import org.gradle.api.provider.ListProperty
 import org.gradle.api.provider.Property
 
+@InternalAPI
 inline fun <reified T> PropertyFactory.single(): Property<T> =
 	property(T::class.java)
 
+@InternalAPI
 inline fun <reified T> PropertyFactory.list(): ListProperty<T> =
 	listProperty(T::class.java)
 
+@InternalAPI
 fun PropertyFactory.boolean(): Property<Boolean> =
 	property(Boolean::class.javaObjectType)
 
+@InternalAPI
 fun PropertyFactory.boolean(default: Boolean): Property<Boolean> =
 	property(Boolean::class.javaObjectType).convention(default)
 
+@InternalAPI
 fun PropertyFactory.booleanList(): ListProperty<Boolean> =
 	listProperty(Boolean::class.javaObjectType)
 
+@InternalAPI
 inline fun <reified T> PropertyFactory.single(default: T): Property<T> =
 	property(T::class.java).convention(default)

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/bot/KordExBotHelper.kt

@@ -6,13 +6,15 @@
 
 package dev.kordex.gradle.plugins.kordex.bot
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.VersionContainer
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
 import dev.kordex.gradle.plugins.kordex.helpers.ApplicationPluginHelper
 import org.gradle.api.Project
 import org.gradle.api.tasks.SourceSetContainer
 import java.util.*
 
+@InternalAPI
 object KordExBotHelper {
 	fun process(target: Project, extension: KordExExtension, versions: VersionContainer) {
 		if (extension.bot.mainClass.isPresent) {

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/bot/KordExBotSettings.kt

@@ -4,9 +4,12 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+@file:OptIn(InternalAPI::class)
+
 package dev.kordex.gradle.plugins.kordex.bot
 
 import dev.kordex.gradle.plugins.kordex.DataCollection
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.boolean
 import dev.kordex.gradle.plugins.kordex.single
 import org.gradle.api.internal.provider.PropertyFactory

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/functions/_CheckTask.kt

@@ -6,6 +6,7 @@
 
 package dev.kordex.gradle.plugins.kordex.functions
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.VersionContainer
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
 import org.gradle.api.Project
@@ -17,6 +18,7 @@ import org.gradle.api.provider.Provider
 private val kotlinJarRegex = "kotlin-gradle-plugin-(.+)-gradle\\d+\\.jar".toRegex()
 
 @Suppress("UnstableApiUsage", "StringLiteralDuplication")
+@InternalAPI
 fun Project.checkTask(
 	extension: KordExExtension,
 	versionsProvider: Provider<VersionContainer>,

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/functions/_ConfigurationsProvider.kt

@@ -6,9 +6,11 @@
 
 package dev.kordex.gradle.plugins.kordex.functions
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
 import org.gradle.api.provider.ProviderFactory
 
+@InternalAPI
 fun ProviderFactory.configurationsProvider(extension: KordExExtension) = provider {
 	if (extension.configurations.isPresent && extension.configurations.get().isNotEmpty()) {
 		extension.configurations.get().toTypedArray()

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/functions/_PackageProvider.kt

@@ -6,12 +6,14 @@
 
 package dev.kordex.gradle.plugins.kordex.functions
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.PackageContainer
 import dev.kordex.gradle.plugins.kordex.VersionContainer
 import dev.kordex.gradle.plugins.kordex.isKX2
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
 
+@InternalAPI
 fun ProviderFactory.packageProvider(versionsProvider: Provider<VersionContainer>) = provider {
 	val versions = versionsProvider.get()
 

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/functions/_VersionsProvider.kt

@@ -6,6 +6,7 @@
 
 package dev.kordex.gradle.plugins.kordex.functions
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.Version
 import dev.kordex.gradle.plugins.kordex.VersionContainer
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
@@ -14,6 +15,7 @@ import dev.kordex.gradle.plugins.kordex.base.latestKordMetadata
 import dev.kordex.gradle.plugins.kordex.resolvers.GradleMetadataResolver
 import org.gradle.api.provider.ProviderFactory
 
+@InternalAPI
 fun ProviderFactory.versionsProvider(extension: KordExExtension) = provider {
 	val kordExVersion = if (!extension.kordExVersion.isPresent || extension.kordExVersion.orNull == "latest") {
 		latestKordExMetadata?.getCurrentVersion()

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/helpers/ApplicationPluginHelper.kt

@@ -6,6 +6,7 @@
 
 package dev.kordex.gradle.plugins.kordex.helpers
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
 import org.gradle.api.Project
 import org.gradle.api.plugins.ApplicationPlugin
@@ -18,6 +19,7 @@ import org.slf4j.LoggerFactory
 import java.io.File
 import kotlin.jvm.java
 
+@InternalAPI
 object ApplicationPluginHelper {
 	private val logger = LoggerFactory.getLogger(ApplicationPluginHelper::class.java)
 

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/helpers/I18nHelper.kt

@@ -6,7 +6,8 @@
 
 package dev.kordex.gradle.plugins.kordex.helpers
 
-import dev.kordex.gradle.plugins.kordex.base.KordExExtension
+import dev.kordex.gradle.plugins.kordex.InternalAPI
+import dev.kordex.gradle.plugins.kordex.i18n.KordExI18nSettings
 import dev.kordex.i18n.generator.TranslationsClass
 import org.gradle.api.Project
 import org.gradle.api.tasks.SourceSetContainer
@@ -15,11 +16,12 @@ import java.nio.charset.MalformedInputException
 import java.nio.file.Files
 import java.util.Properties
 
+@InternalAPI
 object I18nHelper {
-	fun apply(target: Project, extension: KordExExtension) {
+	fun apply(target: Project, extension: KordExI18nSettings) {
 		validate(extension)
 
-		var bundle = extension.i18n.translationBundle.get().split(".")
+		var bundle = extension.translationBundle.get().split(".")
 
 		if (bundle.size == 1) {
 			bundle = bundle + "strings"
@@ -36,7 +38,7 @@ object I18nHelper {
 			error("Cannot find translation bundle file: ${inputFile.absolutePath}")
 		}
 
-		val outputDirectory = extension.i18n.outputDirectory.orNull
+		val outputDirectory = extension.outputDirectory.orNull
 			?: target.layout.buildDirectory.file("generated/kordex/main/kotlin/").get().asFile
 
 		val generateTask = target.tasks.create("generateTranslationsClass") {
@@ -59,9 +61,9 @@ object I18nHelper {
 					val translationsClass = TranslationsClass(
 						bundle = bundle.joinToString("."),
 						allProps = props,
-						className = extension.i18n.className.get(),
-						classPackage = extension.i18n.classPackage.get(),
-						publicVisibility = extension.i18n.publicVisibility.get()
+						className = extension.className.get(),
+						classPackage = extension.classPackage.get(),
+						publicVisibility = extension.publicVisibility.get()
 					)
 
 					translationsClass.writeTo(outputDirectory)
@@ -78,7 +80,7 @@ object I18nHelper {
 			dependsOn(generateTask)
 		}
 
-		if (extension.i18n.configureSourceSet.get()) {
+		if (extension.configureSourceSet.get()) {
 			sourceSet {
 				java {
 					srcDir(outputDirectory)
@@ -92,10 +94,10 @@ object I18nHelper {
 		}
 	}
 
-	fun validate(extension: KordExExtension) {
+	fun validate(extension: KordExI18nSettings) {
 		val requiredProperties = mapOf(
-			"i18n -> classPackage" to extension.i18n.classPackage,
-			"i18n -> translationBundle" to extension.i18n.translationBundle,
+			"i18n -> classPackage" to extension.classPackage,
+			"i18n -> translationBundle" to extension.translationBundle,
 		)
 
 		requiredProperties.forEach { (key, value) ->

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/helpers/KspPluginHelper.kt

@@ -6,11 +6,13 @@
 
 package dev.kordex.gradle.plugins.kordex.helpers
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import org.gradle.api.Project
 import org.gradle.api.tasks.SourceSetContainer
 import org.gradle.kotlin.dsl.*
 import org.slf4j.LoggerFactory
 
+@InternalAPI
 object KspPluginHelper {
 	private val logger = LoggerFactory.getLogger(KspPluginHelper::class.java)
 

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/i18n/KordExI18nSettings.kt

@@ -4,8 +4,11 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+@file:OptIn(InternalAPI::class)
+
 package dev.kordex.gradle.plugins.kordex.i18n
 
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.boolean
 import dev.kordex.gradle.plugins.kordex.single
 import org.gradle.api.internal.provider.PropertyFactory

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/plugins/KordExPluginHelper.kt

@@ -8,6 +8,7 @@ package dev.kordex.gradle.plugins.kordex.plugins
 
 import com.github.zafarkhaja.semver.ParseException
 import com.github.zafarkhaja.semver.expr.ExpressionParser
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.base.KordExExtension
 import org.gradle.api.Project
 import org.gradle.api.Task
@@ -18,6 +19,7 @@ import org.gradle.api.tasks.bundling.Tar
 import org.gradle.kotlin.dsl.*
 import java.util.*
 
+@InternalAPI
 object KordExPluginHelper {
 	fun process(target: Project, extension: KordExExtension) {
 		validate(target, extension)

kordex/src/main/kotlin/dev/kordex/gradle/plugins/kordex/plugins/KordExPluginSettings.kt

@@ -4,9 +4,12 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+@file:OptIn(InternalAPI::class)
+
 package dev.kordex.gradle.plugins.kordex.plugins
 
 import com.github.zafarkhaja.semver.expr.ExpressionParser
+import dev.kordex.gradle.plugins.kordex.InternalAPI
 import dev.kordex.gradle.plugins.kordex.list
 import dev.kordex.gradle.plugins.kordex.single
 import org.gradle.api.internal.provider.PropertyFactory

testModule/settings.gradle.kts

@@ -1,6 +1,6 @@
 pluginManagement {
 	plugins {
-		val pluginVersion = "1.5.4"
+		val pluginVersion = "1.5.5"
 
 		kotlin("jvm") version "2.0.21"