Skip to content

Document custom options#292

Open
alexander-yevsyukov wants to merge 37 commits intomasterfrom
document-custom-options
Open

Document custom options#292
alexander-yevsyukov wants to merge 37 commits intomasterfrom
document-custom-options

Conversation

@alexander-yevsyukov
Copy link
Copy Markdown
Collaborator

@alexander-yevsyukov alexander-yevsyukov commented Apr 29, 2026

This PR extends the documentation with detailed text in the "Custom validation" section.

Other notable changes

  • The writer skill was improved to update the navigation bar when content changes and use footnote-like links in Markdown.

dependabot Bot and others added 7 commits April 24, 2026 18:09
Copilot AI review requested due to automatic review settings April 29, 2026 20:23
…eview/postcss-8.5.10' into document-custom-options
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Updates the project’s published version and aligns related build/documentation metadata, while introducing a Time-related documentation dependency and submodule.

Changes:

  • Bump Validation SDK and related dependency versions across Gradle, Maven POM output, and docs.
  • Add time-validation as a dependency and expose time-validation / time-gradle-plugin coordinates in buildSrc.
  • Add a new docs _time Git submodule and ignore Junie memory output.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
version.gradle.kts Bumps the published Validation SDK version to 2.0.0-SNAPSHOT.415.
pom.xml Updates generated first-level dependency versions and adds io.spine.tools:time-validation.
docs/content/docs/validation/01-getting-started/adding-to-build.md Updates example plugin versions referenced in docs.
dependencies.md Refreshes generated dependency/license report for the new version.
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt Bumps the pinned Validation artifacts version used by build logic.
buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt Bumps Time version and adds helpers for time-validation and time-gradle-plugin.
buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt Bumps Core JVM compiler “dogfooding” version.
buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt Removes an unused import.
buildSrc/build.gradle.kts Removes outdated Shadow plugin compatibility note.
.junie/guidelines.md Generalizes Junie guidance wording to “Spine family of projects”.
.gitmodules Adds docs/_time submodule pointing to SpineEventEngine/time.
.gitignore Ignores .junie/memory/.
Comments suppressed due to low confidence (1)

buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt:73

  • Time now exposes validation and gradlePlugin artifact coordinates, but they are not included in modules. Since modules drives Dependency.artifacts / forceArtifacts(), this makes the dependency metadata incomplete and can lead to these new artifacts not being version-forced when Time is used that way. Add the new artifacts to modules (or document why they are intentionally excluded).
    fun validation(version: String): String = "${Spine.toolsGroup}:time-validation:$version"
    val validation get() = validation(version)

    fun gradlePlugin(version: String): String = "${Spine.toolsGroup}:time-gradle-plugin:$version"
    val gradlePlugin get() = gradlePlugin(version)

    override val modules: List<String>
        get() = listOf(
            lib,
            javaExtensions,
            kotlinExtensions,
            testLib
        ).map {
            it.split(":").let { (g, artifact) -> "$g:$artifact" }
        }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/content/docs/validation/01-getting-started/adding-to-build.md
Copilot AI review requested due to automatic review settings April 30, 2026 19:52
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR updates the Validation SDK snapshot/version references and restructures the “Custom validation” documentation into a multi-page, step-by-step guide (using Spine Time’s (when) option as the running example), keeping the docs navigation in sync.

Changes:

  • Bump Validation SDK snapshot versions and align related build/dependency references (Gradle, Maven, docs preview).
  • Replace the single-page “Custom validation” doc with a structured section under 05-custom-validation/ and update all inbound links + sidenav.
  • Add Spine Time as a docs submodule (docs/_time) and introduce/update internal agent/writer guidance to keep nav in sync.

Reviewed changes

Copilot reviewed 40 out of 43 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
version.gradle.kts Bumps the published Validation SDK snapshot version.
pom.xml Updates project/dependency versions and adds time-validation dependency.
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml Reworks Custom validation nav into a multi-page subtree.
docs/content/docs/validation/_index.md Updates the top-level docs index link to the new Custom validation path.
docs/content/docs/validation/09-developers-guide/key-modules.md Updates “What’s next” link to the new Custom validation section.
docs/content/docs/validation/09-developers-guide/architecture.md Updates “What’s next” link to the new Custom validation section.
docs/content/docs/validation/08-custom-validation/_index.md Removes the old single-page Custom validation doc.
docs/content/docs/validation/05-custom-validation/_index.md Adds the new Custom validation section overview page.
docs/content/docs/validation/05-custom-validation/declare-the-option.md Adds step-by-step doc page for declaring a custom option in Protobuf.
docs/content/docs/validation/05-custom-validation/register-the-option.md Adds step-by-step doc page for registering extensions + wiring ValidationOption.
docs/content/docs/validation/05-custom-validation/declare-event-and-view.md Adds step-by-step doc page for event + projection state protos.
docs/content/docs/validation/05-custom-validation/implement-the-reaction.md Adds step-by-step doc page for implementing a Reaction.
docs/content/docs/validation/05-custom-validation/implement-the-view.md Adds step-by-step doc page for implementing a View.
docs/content/docs/validation/05-custom-validation/implement-the-generator.md Adds step-by-step doc page for implementing a Generator.
docs/content/docs/validation/05-custom-validation/pass-to-compiler.md Adds doc page describing how to put custom options on the Compiler user classpath.
docs/content/docs/validation/05-custom-validation/summary.md Adds recap/summary page for the new section.
docs/content/docs/validation/04-validators/implement-a-validator.md Updates “What’s next” link to new Custom validation section.
docs/content/docs/validation/04-validators/_index.md Updates Custom validation links to new section path.
docs/content/docs/validation/03-built-in-options/_index.md Updates Custom validation link to new section path.
docs/content/docs/validation/02-concepts/options-overview.md Adjusts link formatting and updates Custom validation link.
docs/content/docs/validation/02-concepts/error-messages.md Updates Custom validation link to new section path.
docs/content/docs/validation/02-concepts/_index.md Adjusts link formatting and updates Custom validation links.
docs/content/docs/validation/01-getting-started/generated-code.md Updates Custom validation link to new section path.
docs/content/docs/validation/01-getting-started/adding-to-build.md Updates referenced plugin versions for Validation + CoreJvm.
docs/_preview/package.json Updates postcss dev dependency version.
docs/_preview/package-lock.json Locks postcss to the updated version and updates metadata.
dependencies.md Regenerates dependency/license report for the new snapshot version.
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt Bumps pinned Validation dependency version used by the build.
buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt Bumps Spine Time version and adds coordinates helpers for Time validation/plugin artifacts.
buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt Bumps CoreJvm Compiler/plugin versions used by the build.
buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt Removes an unused import.
buildSrc/build.gradle.kts Removes outdated Shadow-plugin compatibility note (Shadow version unchanged here).
.junie/guidelines.md Updates Junie guidelines wording to cover Spine family projects.
.gitmodules Adds docs/_time submodule pointing to Spine Time repository.
.gitignore Ignores .junie/memory/ workspace artifacts.
.agents/tasks/extend-custom-validation-docs.md Adds/records a task spec for expanding Custom validation docs.
.agents/tasks/document-passing-custom-validation.md Adds/records a task spec for documenting classpath passing for custom options.
.agents/skills/writer/agents/openai.yaml Updates writer agent prompt to keep sidenav in sync and avoid historical doc edits.
.agents/skills/writer/SKILL.md Documents the repo convention to keep current sidenav.yml in sync with docs changes.
Files not reviewed (1)
  • docs/_preview/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/data/docs/validation/2-0-0-snapshot/sidenav.yml
Comment thread .agents/tasks/document-passing-custom-validation.md Outdated
Comment thread .agents/tasks/document-passing-custom-validation.md Outdated
@alexander-yevsyukov alexander-yevsyukov self-assigned this Apr 30, 2026
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings April 30, 2026 20:05
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Updates the Validation documentation to provide a step-by-step guide for implementing custom validation options (based on Spine Time’s (when) option), while also bumping internal dependency/version pins and adjusting docs navigation to reflect the new structure.

Changes:

  • Restructures “Custom validation” docs into a dedicated 05-custom-validation/ section with multiple focused pages and updates all inbound links/navigation.
  • Adds a docs/_time submodule reference and updates related dependency coordinates/versions (Validation, Spine Time, Core JVM plugins).
  • Refreshes generated artifacts and tooling metadata (dependency report, generated POM, docs preview PostCSS).

Reviewed changes

Copilot reviewed 40 out of 43 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
version.gradle.kts Bumps the published Validation SDK version.
pom.xml Updates generated dependency list + adds time-validation dependency.
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml Replaces single “Custom validation” page with a nested section and new pages.
docs/content/docs/validation/_index.md Updates main landing-page link to the new custom validation section path.
docs/content/docs/validation/09-developers-guide/key-modules.md Updates “What’s next” link to the new custom validation path.
docs/content/docs/validation/09-developers-guide/architecture.md Updates “What’s next” link to the new custom validation path.
docs/content/docs/validation/08-custom-validation/_index.md Removes the old custom validation page.
docs/content/docs/validation/05-custom-validation/_index.md Adds new custom validation section overview page.
docs/content/docs/validation/05-custom-validation/declare-the-option.md New page: declaring custom options in Protobuf.
docs/content/docs/validation/05-custom-validation/register-the-option.md New page: registering options via OptionsProvider + ValidationOption.
docs/content/docs/validation/05-custom-validation/declare-event-and-view.md New page: event + projection state proto definitions.
docs/content/docs/validation/05-custom-validation/implement-the-reaction.md New page: implementing a Reaction for custom options.
docs/content/docs/validation/05-custom-validation/implement-the-view.md New page: implementing a projection View.
docs/content/docs/validation/05-custom-validation/implement-the-generator.md New page: implementing an OptionGenerator.
docs/content/docs/validation/05-custom-validation/pass-to-compiler.md New page: explaining how to place options on the compiler user classpath.
docs/content/docs/validation/05-custom-validation/summary.md New page: recap of the custom option workflow.
docs/content/docs/validation/04-validators/implement-a-validator.md Updates “What’s next” link to the new custom validation path.
docs/content/docs/validation/04-validators/_index.md Updates custom validation link to the new section path.
docs/content/docs/validation/03-built-in-options/_index.md Updates custom validation link to the new section path.
docs/content/docs/validation/02-concepts/options-overview.md Updates link formatting and custom validation link path.
docs/content/docs/validation/02-concepts/error-messages.md Updates custom validation link path.
docs/content/docs/validation/02-concepts/_index.md Updates link formatting and custom validation link path.
docs/content/docs/validation/01-getting-started/generated-code.md Updates custom validation link path.
docs/content/docs/validation/01-getting-started/adding-to-build.md Updates referenced plugin versions in examples.
docs/_preview/package.json Bumps PostCSS version for docs preview tooling.
docs/_preview/package-lock.json Locks PostCSS bump and updates package metadata.
dependencies.md Regenerates dependency/license report with updated versions and timestamps.
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt Bumps pinned Validation dependency version constant.
buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt Bumps Spine Time version and adds time-validation/time-gradle-plugin coordinates.
buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt Bumps Core JVM compiler/plugin version constants and updates copyright year.
buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt Removes an unused import.
buildSrc/build.gradle.kts Removes outdated Shadow-plugin compatibility note.
.junie/guidelines.md Updates Junie assistant guidance text.
.gitmodules Adds docs/_time submodule entry.
.gitignore Ignores .junie/memory/.
.agents/tasks/extend-custom-validation-docs.md Adds an agent task spec for extending custom validation docs.
.agents/tasks/document-passing-custom-validation.md Adds an agent task spec for documenting classpath wiring.
.agents/skills/writer/agents/openai.yaml Updates writer agent default prompt to emphasize nav sync and versioning rules.
.agents/skills/writer/SKILL.md Documents the “keep docs navigation in sync” convention.
Files not reviewed (1)
  • docs/_preview/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines 36 to 41
/**
* The version of the Validation library artifacts.
*/
const val version = "2.0.0-SNAPSHOT.413"
const val version = "2.0.0-SNAPSHOT.414"

/**
Comment thread docs/data/docs/validation/2-0-0-snapshot/sidenav.yml
Comment thread pom.xml
@alexander-yevsyukov alexander-yevsyukov marked this pull request as ready for review April 30, 2026 21:10
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a8230b8bf9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread pom.xml Outdated
<groupId>io.spine</groupId>
<artifactId>spine-time</artifactId>
<version>2.0.0-SNAPSHOT.235</version>
<version>2.0.0-SNAPSHOT.236</version>
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Regenerate POM with current Spine Time artifact versions

The checked-in generated pom.xml now advertises spine-time (and time-validation) as 2.0.0-SNAPSHOT.236, but the build dependency source was bumped to 2.0.0-SNAPSHOT.237 in buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt. This leaves the dependency report out of sync with the build’s actual resolved Time artifacts, which can mislead release/audit tooling and reviewers that rely on pom.xml as the canonical first-level dependency snapshot.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR restructures and expands the Validation documentation around “Custom validation” into a multi-page workflow, and updates build/docs metadata to newer snapshot versions.

Changes:

  • Replace the single “Custom validation” page with a new multi-page 05-custom-validation/ section and update all internal links/navigation accordingly.
  • Bump published snapshot versions across Gradle/Maven/docs examples, plus update some dependency pins (e.g., postcss).
  • Add the Spine Time repository as a docs submodule (docs/_time) and extend local dependency helpers for Time.

Reviewed changes

Copilot reviewed 43 out of 46 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
version.gradle.kts Bumps Validation publish version to .415.
pom.xml Updates generated POM versions/deps; adds time-validation dependency.
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml Reworks nav: “Custom validation” becomes a multi-page section.
docs/content/docs/validation/_index.md Updates root docs link to new custom validation path.
docs/content/docs/validation/09-developers-guide/key-modules.md Updates link to new custom validation path.
docs/content/docs/validation/09-developers-guide/architecture.md Updates link to new custom validation path.
docs/content/docs/validation/08-custom-validation/_index.md Removes old single-page custom validation doc.
docs/content/docs/validation/05-custom-validation/_index.md Adds new “Overview” page for custom validation section.
docs/content/docs/validation/05-custom-validation/declare-the-option.md Adds step: declaring a custom option in Protobuf.
docs/content/docs/validation/05-custom-validation/register-the-option.md Adds step: registering proto extension + ValidationOption.
docs/content/docs/validation/05-custom-validation/declare-event-and-view.md Adds step: define discovery event and view state.
docs/content/docs/validation/05-custom-validation/implement-the-reaction.md Adds step: implement Reaction for the option.
docs/content/docs/validation/05-custom-validation/implement-the-view.md Adds step: implement View projection.
docs/content/docs/validation/05-custom-validation/implement-the-generator.md Adds step: implement generator and querying pattern.
docs/content/docs/validation/05-custom-validation/pass-to-compiler.md Adds step: place option implementation on compiler classpath.
docs/content/docs/validation/05-custom-validation/summary.md Adds recap page for the workflow.
docs/content/docs/validation/04-validators/implement-a-validator.md Updates “What’s next” link to new custom validation path.
docs/content/docs/validation/04-validators/_index.md Updates references to new custom validation path.
docs/content/docs/validation/03-built-in-options/_index.md Updates “What’s next” link to new custom validation path.
docs/content/docs/validation/02-concepts/options-overview.md Minor wording/formatting + updates custom validation link.
docs/content/docs/validation/02-concepts/error-messages.md Updates custom validation link.
docs/content/docs/validation/02-concepts/_index.md Minor wording/formatting + updates custom validation link.
docs/content/docs/validation/01-getting-started/generated-code.md Updates custom validation link.
docs/content/docs/validation/01-getting-started/adding-to-build.md Updates plugin version examples (validation / core-jvm).
docs/_preview/package.json Bumps postcss dev dependency.
docs/_preview/package-lock.json Lockfile update for postcss.
dependencies.md Regenerates dependency/license report for .415.
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt Bumps local Validation dependency version constant.
buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt Bumps Time version; adds time-validation and Time Gradle plugin aliases.
buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt Bumps CoreJvm compiler plugin versions.
buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt Removes an unused import.
buildSrc/build.gradle.kts Removes outdated Shadow plugin compatibility comment.
.junie/guidelines.md Updates Junie guidelines wording.
.gitmodules Adds docs/_time submodule pointing to Spine Time repo.
.gitignore Ignores .junie/memory/.
.agents/skills/writer/agents/openai.yaml Updates writer agent prompt (nav sync + footnote-link preference).
.agents/skills/writer/SKILL.md Expands writer skill guidance (nav sync + link style).
Files not reviewed (1)
  • docs/_preview/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

* The version of the Validation library artifacts.
*/
const val version = "2.0.0-SNAPSHOT.413"
const val version = "2.0.0-SNAPSHOT.414"
Comment thread pom.xml
Comment thread pom.xml
Comment on lines 63 to 66
<groupId>io.spine</groupId>
<artifactId>spine-validation-jvm-runtime</artifactId>
<version>2.0.0-SNAPSHOT.411</version>
<version>2.0.0-SNAPSHOT.414</version>
<scope>compile</scope>
Comment thread pom.xml
Comment thread pom.xml
Comment on lines 289 to 293
<dependency>
<groupId>io.spine.tools</groupId>
<artifactId>validation-java-bundle</artifactId>
<version>2.0.0-SNAPSHOT.411</version>
<version>2.0.0-SNAPSHOT.414</version>
</dependency>
Comment on lines +74 to +76
Both `OptionsProvider` and `ValidationOption` are discovered via Java `ServiceLoader`, so the
`@AutoService` annotation must be present and the annotation processor must run during
compilation.
Copy link
Copy Markdown
Collaborator

@armiol armiol left a comment

Choose a reason for hiding this comment

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

@alexander-yevsyukov LGTM in general. Please see one comment and one suggestion.

}
```

The `id` field must be the **first** field and must be the same type that the `View` uses as its
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Which "first"? Have the index == 1?

headline: Documentation
---

# Implement the `Generator`
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

In this section it would be good to have the code for the class. Perhaps, write it step-by-step, and print it at the end with a summary of some sort.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants