diff --git a/.agents/documentation-guidelines.md b/.agents/documentation-guidelines.md index 914dcc873..6c9c1bae7 100644 --- a/.agents/documentation-guidelines.md +++ b/.agents/documentation-guidelines.md @@ -9,6 +9,6 @@ ## Avoid widows, runts, orphans, or rivers Agents should **AVOID** text flow patters illustrated -on [this diagram](widow-runt-orphan-river.jpg). +on [this diagram](widow-runt-orphan.jpg). [todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md new file mode 100644 index 000000000..3e3b9840b --- /dev/null +++ b/.agents/skills/writer/SKILL.md @@ -0,0 +1,46 @@ +--- +name: writer +description: Write, edit, and restructure user-facing and developer-facing documentation. Use when asked to create/update docs such as `README.md`, `docs/**`, and other Markdown documentation; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples. +--- + +# Write documentation (repo-specific) + +## Decide the target and audience + +- Identify the target reader: end user, contributor, maintainer, or tooling/automation. +- Identify the task type: new doc, update, restructure, or documentation audit. +- Identify the acceptance criteria: “what is correct when the reader is done?” + +## Choose where the content should live + +- Prefer updating an existing doc over creating a new one. +- Place content in the most discoverable location: + - `README.md`: project entry point and “what is this?”. + - `docs/`: longer-form docs (follow existing conventions in that tree). + - Source KDoc: API usage, examples, and semantics that belong with the code. + +## Follow local documentation conventions + +- Follow `.agents/documentation-guidelines.md` and `.agents/documentation-tasks.md`. +- Use fenced code blocks for commands and examples; format file/dir names as code. +- Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed. + +## Make docs actionable + +- Prefer steps the reader can execute (commands + expected outcome). +- Prefer concrete examples over abstract descriptions. +- Include prerequisites (versions, OS, environment) when they are easy to miss. +- Use consistent terminology (match code identifiers and existing docs). + +## KDoc-specific guidance + +- For public/internal APIs, include at least one example snippet demonstrating common usage. +- When converting from Javadoc/inline comments to KDoc: + - Remove HTML like `

` and preserve meaning. + - Prefer short paragraphs and blank lines over HTML formatting. + +## Validate changes + +- For code changes, follow `.agents/running-builds.md`. +- For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`. + diff --git a/.agents/skills/writer/agents/openai.yaml b/.agents/skills/writer/agents/openai.yaml new file mode 100644 index 000000000..44eaa4e24 --- /dev/null +++ b/.agents/skills/writer/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writer" + short_description: "Write and update user/developer docs" + default_prompt: "Write or revise documentation in this repository (for example: README.md, docs/**, CONTRIBUTING.md, and API documentation/KDoc). Follow local documentation guidelines in .agents/*.md, keep changes concise and actionable, and include concrete examples and commands where appropriate." + diff --git a/.agents/skills/writer/assets/templates/doc-page.md b/.agents/skills/writer/assets/templates/doc-page.md new file mode 100644 index 000000000..f405b71e1 --- /dev/null +++ b/.agents/skills/writer/assets/templates/doc-page.md @@ -0,0 +1,23 @@ +# Title + +## Goal + +State what the reader will accomplish. + +## Prerequisites + +- List versions/tools the reader needs. + +## Steps + +1. Do the first thing. +2. Do the next thing. + +## Verify + +Show how the reader can confirm success. + +## Troubleshooting + +- Common failure: likely cause → fix. + diff --git a/.agents/skills/writer/assets/templates/kdoc-example.md b/.agents/skills/writer/assets/templates/kdoc-example.md new file mode 100644 index 000000000..fdbd9b6a0 --- /dev/null +++ b/.agents/skills/writer/assets/templates/kdoc-example.md @@ -0,0 +1,11 @@ +````kotlin +/** + * Explain what this API does in one sentence. + * + * ## Example + * ```kotlin + * // Show the typical usage pattern. + * val result = doThing() + * ``` + */ +```` diff --git a/.agents/skills/writer/assets/templates/kotlin-java-example.md b/.agents/skills/writer/assets/templates/kotlin-java-example.md new file mode 100644 index 000000000..5517516f5 --- /dev/null +++ b/.agents/skills/writer/assets/templates/kotlin-java-example.md @@ -0,0 +1,13 @@ +{{< code-tabs langs="Kotlin, Java">}} + +{{< code-tab lang="Kotlin" >}} +```kotlin +``` +{{< /code-tab >}} + +{{< code-tab lang="Java" >}} +```java +``` +{{< /code-tab >}} + +{{< /code-tabs >}} diff --git a/.agents/widow-runt-orphan.jpg b/.agents/widow-runt-orphan.jpg new file mode 100644 index 000000000..284b02a47 Binary files /dev/null and b/.agents/widow-runt-orphan.jpg differ diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index 9127fed11..691d6b707 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -75,7 +75,7 @@ val grGitVersion = "4.1.1" * This version may change from the [version of Kotlin][io.spine.dependency.lib.Kotlin.version] * used by the project. */ -val kotlinEmbeddedVersion = "2.2.21" +val kotlinEmbeddedVersion = "2.3.10" /** * The version of Guava used in `buildSrc`. @@ -83,7 +83,7 @@ val kotlinEmbeddedVersion = "2.2.21" * Always use the same version as the one specified in [io.spine.dependency.lib.Guava]. * Otherwise, when testing Gradle plugins, clashes may occur. */ -val guavaVersion = "33.4.8-jre" +val guavaVersion = "33.5.0-jre" /** * The version of ErrorProne Gradle plugin. @@ -103,7 +103,7 @@ val errorPronePluginVersion = "4.2.0" * @see * Protobuf Gradle Plugins Releases */ -val protobufPluginVersion = "0.9.5" +val protobufPluginVersion = "0.9.6" /** * The version of Dokka Gradle Plugins. diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt b/buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt index d2762bdb8..111443019 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt @@ -39,7 +39,7 @@ object Kotlin : DependencyWithBom() { * depend on Gradle and the version of embedded Kotlin. */ @Suppress("MemberVisibilityCanBePrivate") // used directly from the outside. - const val runtimeVersion = "2.2.21" + const val runtimeVersion = "2.3.10" override val version = runtimeVersion override val group = "org.jetbrains.kotlin" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/lib/Protobuf.kt b/buildSrc/src/main/kotlin/io/spine/dependency/lib/Protobuf.kt index 4889ea128..0a432d413 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/lib/Protobuf.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/lib/Protobuf.kt @@ -33,7 +33,7 @@ package io.spine.dependency.lib ) object Protobuf { const val group = "com.google.protobuf" - const val version = "4.33.2" + const val version = "4.34.0" /** * The Java library with Protobuf data types. @@ -64,7 +64,7 @@ object Protobuf { * * When changing the version, also change the version used in the `build.gradle.kts`. */ - const val version = "0.9.5" + const val version = "0.9.6" const val id = "com.google.protobuf" const val lib = "$group:protobuf-gradle-plugin:$version" } diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt index 38346ab0c..7e4b1c3b8 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt @@ -33,8 +33,8 @@ package io.spine.dependency.local */ @Suppress("ConstPropertyName", "unused") object Base { - const val version = "2.0.0-SNAPSHOT.384" - const val versionForBuildScript = "2.0.0-SNAPSHOT.384" + const val version = "2.0.0-SNAPSHOT.385" + const val versionForBuildScript = "2.0.0-SNAPSHOT.385" const val group = Spine.group private const val prefix = "spine" const val libModule = "$prefix-base" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Change.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Change.kt index dbde19350..7809c9cd6 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Change.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Change.kt @@ -33,7 +33,7 @@ package io.spine.dependency.local */ @Suppress("ConstPropertyName") object Change { - const val version = "2.0.0-SNAPSHOT.205" + const val version = "2.0.0-SNAPSHOT.206" const val group = Spine.group const val artifact = "spine-change" const val lib = "$group:$artifact:$version" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt index ff1ad47ec..304cbf4a9 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt @@ -72,7 +72,7 @@ object Compiler : Dependency() { * The version of the Compiler dependencies. */ override val version: String - private const val fallbackVersion = "2.0.0-SNAPSHOT.038" + private const val fallbackVersion = "2.0.0-SNAPSHOT.039" /** * The distinct version of the Compiler used by other build tools. @@ -81,7 +81,7 @@ object Compiler : Dependency() { * transitive dependencies, this is the version used to build the project itself. */ val dogfoodingVersion: String - private const val fallbackDfVersion = "2.0.0-SNAPSHOT.038" + private const val fallbackDfVersion = "2.0.0-SNAPSHOT.039" /** * The artifact for the Compiler Gradle plugin. diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt index 2737c39cf..fb5761458 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt @@ -46,12 +46,12 @@ object CoreJvmCompiler { /** * The version used to in the build classpath. */ - const val dogfoodingVersion = "2.0.0-SNAPSHOT.050" + const val dogfoodingVersion = "2.0.0-SNAPSHOT.054" /** * The version to be used for integration tests. */ - const val version = "2.0.0-SNAPSHOT.050" + const val version = "2.0.0-SNAPSHOT.054" /** * The ID of the Gradle plugin. diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/ModelCompiler.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/ModelCompiler.kt index 5f9e54117..fb4359d89 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/ModelCompiler.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/ModelCompiler.kt @@ -33,7 +33,7 @@ package io.spine.dependency.local */ @Suppress("ConstPropertyName") object ModelCompiler { - const val version = "2.0.0-SNAPSHOT.133" + const val version = "2.0.0-SNAPSHOT.200" const val group = Spine.toolsGroup const val artifact = "spine-model-compiler" const val lib = "$group:$artifact:$version" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt index 3de642eb4..1d0481d8e 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt @@ -33,7 +33,7 @@ package io.spine.dependency.local */ @Suppress("ConstPropertyName") object Time { - const val version = "2.0.0-SNAPSHOT.231" + const val version = "2.0.0-SNAPSHOT.232" const val group = Spine.group const val artifact = "spine-time" const val lib = "$group:$artifact:$version" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/ToolBase.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/ToolBase.kt index 1df8dd1f4..5e443139b 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/ToolBase.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/ToolBase.kt @@ -34,8 +34,8 @@ package io.spine.dependency.local @Suppress("ConstPropertyName", "unused") object ToolBase { const val group = Spine.toolsGroup - const val version = "2.0.0-SNAPSHOT.371" - const val dogfoodingVersion = "2.0.0-SNAPSHOT.371" + const val version = "2.0.0-SNAPSHOT.373" + const val dogfoodingVersion = "2.0.0-SNAPSHOT.373" const val lib = "$group:tool-base:$version" const val classicCodegen = "$group:classic-codegen:$version" diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt index 1cad8b740..1ef4f097a 100644 --- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt +++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt @@ -36,7 +36,7 @@ object Validation { /** * The version of the Validation library artifacts. */ - const val version = "2.0.0-SNAPSHOT.393" + const val version = "2.0.0-SNAPSHOT.402" /** * The last version of Validation compatible with ProtoData. diff --git a/buildSrc/src/main/kotlin/io/spine/gradle/kotlin/KotlinConfig.kt b/buildSrc/src/main/kotlin/io/spine/gradle/kotlin/KotlinConfig.kt index 4539aa900..d251a54a6 100644 --- a/buildSrc/src/main/kotlin/io/spine/gradle/kotlin/KotlinConfig.kt +++ b/buildSrc/src/main/kotlin/io/spine/gradle/kotlin/KotlinConfig.kt @@ -28,7 +28,9 @@ package io.spine.gradle.kotlin import org.gradle.jvm.toolchain.JavaLanguageVersion import org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerOptions +import org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompilerOptions import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension +import org.jetbrains.kotlin.gradle.dsl.JvmDefaultMode /** * Sets [Java toolchain](https://kotlinlang.org/docs/gradle.html#gradle-java-toolchains-support) @@ -53,10 +55,12 @@ fun KotlinJvmProjectExtension.applyJvmToolchain(version: String) = */ @Suppress("unused") fun KotlinCommonCompilerOptions.setFreeCompilerArgs() { + if (this is KotlinJvmCompilerOptions) { + jvmDefault.set(JvmDefaultMode.ENABLE) + } freeCompilerArgs.addAll( listOf( "-Xskip-prerelease-check", - "-Xjvm-default=all", "-Xinline-classes", "-Xexpect-actual-classes", "-Xcontext-parameters", diff --git a/buildSrc/src/main/kotlin/io/spine/gradle/testing/Logging.kt b/buildSrc/src/main/kotlin/io/spine/gradle/testing/Logging.kt index 6fb7eabca..75af960e2 100644 --- a/buildSrc/src/main/kotlin/io/spine/gradle/testing/Logging.kt +++ b/buildSrc/src/main/kotlin/io/spine/gradle/testing/Logging.kt @@ -28,9 +28,9 @@ package io.spine.gradle.testing import org.gradle.api.tasks.testing.Test import org.gradle.api.tasks.testing.TestDescriptor +import org.gradle.api.tasks.testing.TestListener import org.gradle.api.tasks.testing.TestResult import org.gradle.api.tasks.testing.logging.TestExceptionFormat -import org.gradle.kotlin.dsl.KotlinClosure2 /** * Configures logging of this [Test] task. @@ -70,19 +70,16 @@ fun Test.configureLogging() { >> $skippedTestCount skipped """ - afterSuite( - - // `GroovyInteroperability` is employed as `afterSuite()` has no equivalent in Kotlin DSL. - // See issue: https://github.com/gradle/gradle/issues/5431 - - KotlinClosure2({ descriptor, result -> + val listener = object : TestListener { + override fun afterSuite(descriptor: TestDescriptor, result: TestResult) { // If the descriptor has no parent, then it is the root test suite, // i.e. it includes the info about all the run tests. - if (descriptor.parent == null) { logger.lifecycle(result.summary()) } - }) - ) + } + } + + addTestListener(listener) }