Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/documentation-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
51 changes: 51 additions & 0 deletions .agents/skills/writer/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
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 `<p>` 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`.

5 changes: 5 additions & 0 deletions .agents/skills/writer/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -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."

23 changes: 23 additions & 0 deletions .agents/skills/writer/assets/templates/doc-page.md
Original file line number Diff line number Diff line change
@@ -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.

11 changes: 11 additions & 0 deletions .agents/skills/writer/assets/templates/kdoc-example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
````kotlin
/**
* Explain what this API does in one sentence.
*
* ## Example
* ```kotlin
* // Show the typical usage pattern.
* val result = doThing()
* ```
*/
````
13 changes: 13 additions & 0 deletions .agents/skills/writer/assets/templates/kotlin-java-example.md
Original file line number Diff line number Diff line change
@@ -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 >}}
Binary file added .agents/widow-runt-orphan.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 3 additions & 3 deletions buildSrc/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -75,15 +75,15 @@ 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`.
*
* 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.
Expand All @@ -103,7 +103,7 @@ val errorPronePluginVersion = "4.2.0"
* @see <a href="https://github.com/google/protobuf-gradle-plugin/releases">
* Protobuf Gradle Plugins Releases</a>
*/
val protobufPluginVersion = "0.9.5"
val protobufPluginVersion = "0.9.6"

/**
* The version of Dokka Gradle Plugins.
Expand Down
2 changes: 1 addition & 1 deletion buildSrc/src/main/kotlin/io/spine/dependency/build/Ksp.kt
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ import io.spine.dependency.Dependency
*/
@Suppress("unused")
object Ksp : Dependency() {
override val version = "2.3.0"
override val version = "2.3.6"
val dogfoodingVersion = version
override val group = "com.google.devtools.ksp"

Expand Down
2 changes: 1 addition & 1 deletion buildSrc/src/main/kotlin/io/spine/dependency/lib/Kotlin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions buildSrc/src/main/kotlin/io/spine/dependency/lib/Protobuf.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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"
}
Expand Down
4 changes: 2 additions & 2 deletions buildSrc/src/main/kotlin/io/spine/dependency/local/Base.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.037"
private const val fallbackVersion = "2.0.0-SNAPSHOT.039"

/**
* The distinct version of the Compiler used by other build tools.
Expand All @@ -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.037"
private const val fallbackDfVersion = "2.0.0-SNAPSHOT.039"

/**
* The artifact for the Compiler Gradle plugin.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,12 @@ object CoreJvmCompiler {
/**
* The version used to in the build classpath.
*/
const val dogfoodingVersion = "2.0.0-SNAPSHOT.053"
const val dogfoodingVersion = "2.0.0-SNAPSHOT.055"

/**
* The version to be used for integration tests.
*/
const val version = "2.0.0-SNAPSHOT.053"
const val version = "2.0.0-SNAPSHOT.055"

/**
* The ID of the Gradle plugin.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.372"
const val dogfoodingVersion = "2.0.0-SNAPSHOT.372"
const val version = "2.0.0-SNAPSHOT.373"
const val dogfoodingVersion = "2.0.0-SNAPSHOT.374"

const val lib = "$group:tool-base:$version"
const val classicCodegen = "$group:classic-codegen:$version"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ object Validation {
/**
* The version of the Validation library artifacts.
*/
const val version = "2.0.0-SNAPSHOT.394"
const val version = "2.0.0-SNAPSHOT.404"

/**
* The last version of Validation compatible with ProtoData.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -53,10 +55,12 @@ fun KotlinJvmProjectExtension.applyJvmToolchain(version: String) =
*/
@Suppress("unused")
fun KotlinCommonCompilerOptions.setFreeCompilerArgs() {
if (this is KotlinJvmCompilerOptions) {
jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
}
freeCompilerArgs.addAll(
listOf(
"-Xskip-prerelease-check",
"-Xjvm-default=all",
"-Xinline-classes",
"-Xexpect-actual-classes",
"-Xcontext-parameters",
Expand Down
8 changes: 6 additions & 2 deletions buildSrc/src/main/kotlin/io/spine/gradle/repo/Repositories.kt
Original file line number Diff line number Diff line change
Expand Up @@ -96,11 +96,14 @@ fun RepositoryHandler.spineArtifacts(): MavenArtifactRepository = maven {
val RepositoryHandler.intellijReleases: MavenArtifactRepository
get() = maven("https://www.jetbrains.com/intellij-repository/releases")

val RepositoryHandler.jetBrainsCacheRedirector: MavenArtifactRepository
get() = maven("https://cache-redirector.jetbrains.com/intellij-dependencies")

val RepositoryHandler.intellijDependencies: MavenArtifactRepository
get() = maven("https://packages.jetbrains.team/maven/p/ij/intellij-dependencies") {
content {
includeGroupByRegex("com\\.jetbrains\\.intellij.*")
includeGroupByRegex("org\\.jetbrains\\.intellij.*")
includeGroupByRegex("com\\.jetbrains.*")
includeGroupByRegex("org\\.jetbrains.*")
includeGroupByRegex("com\\.intellij.*")
}
}
Expand Down Expand Up @@ -129,6 +132,7 @@ fun RepositoryHandler.standardToSpineSdk() {
}

intellijReleases
jetBrainsCacheRedirector
intellijDependencies
Comment on lines +135 to 136
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two concrete resolution risks here: (1) jetBrainsCacheRedirector is added without any content {} restriction, so it may become eligible to serve any group/artifact, potentially changing dependency resolution in hard-to-debug ways depending on repository order. (2) Broadening intellijDependencies filters to org.jetbrains.* / com.jetbrains.* can inadvertently match Kotlin and other JetBrains ecosystem libraries that are typically expected from Maven Central, again affecting resolution. Consider restricting both repositories to only the IntelliJ-specific groups you actually need (or wrapping them in exclusiveContent), and keep the regexes narrowly scoped (e.g., IntelliJ/JetBrains IntelliJ groups) to avoid accidental shadowing.

Copilot uses AI. Check for mistakes.

maven {
Expand Down
17 changes: 7 additions & 10 deletions buildSrc/src/main/kotlin/io/spine/gradle/testing/Logging.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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<TestDescriptor, TestResult, Unit>({ 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)
}
2 changes: 1 addition & 1 deletion config
Loading
Loading