Add text to "Getting started" documentation section by alexander-yevsyukov · Pull Request #267 · SpineEventEngine/validation

alexander-yevsyukov · 2026-02-24T17:32:09Z

This PR adds text to the "Getting started" section of the documentation. Also, the PR adds already added pages to the side navigation block.

Changes in details

Added front matter to the documentation files.
Updated navigation in "What's next" sections by pages.
Updated module documentation in "Developer's guide".
Split pages of "Getting started" section to more focused and detailed pages.
The "Generated code" section now has tabbed code samples for Kotlin and Java.
Added Kotlin DSL implementation comments in the code samples.
Placed images next to the content in the "Developer's guide" section.
Added existing pages to the side navigation bar.

Copilot

Pull request overview

This PR restructures and enhances the Spine Validation documentation, removing Hugo build directives that prevented page rendering and adding navigation structure to the "Getting started" section.

Changes:

Split the "Getting started" flow into distinct pages with clear navigation between them
Added "What's next" navigation sections throughout intro and developer's guide pages
Removed render: never frontmatter to make documentation pages visible
Updated image reference to correct file extension and added documentation plan

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
version.gradle.kts	Incremented snapshot version from 396 to 397
docs/content/docs/validation/_index.md	Added main landing page content with navigation structure
docs/content/docs/validation/developers-guide/_index.md	Removed duplicate directory (without 09- prefix)
docs/content/docs/validation/09-developers-guide/_index.md	Added developer's guide landing page
docs/content/docs/validation/09-developers-guide/architecture.md	Changed to H1 heading and added navigation links
docs/content/docs/validation/09-developers-guide/key-modules.md	Changed to H1 heading and added navigation links
docs/content/docs/validation/08-custom-validation/_index.md	Updated heading, fixed image file extension, added navigation
docs/content/docs/validation/01-getting-started/_index.md	Updated navigation structure and simplified quick path
docs/content/docs/validation/01-getting-started/adding-to-build.md	Updated next step link text
docs/content/docs/validation/01-getting-started/first-model.md	Split into focused page on declaring constraints with revised navigation
docs/content/docs/validation/01-getting-started/build-project.md	New page covering the build step
docs/content/docs/validation/01-getting-started/generated-code.md	New page covering API usage (extracted from first-model.md)
docs/content/docs/validation/00-intro/_index.md	Fixed directory link syntax
docs/content/docs/validation/00-intro/target-audience.md	Added navigation links
docs/content/docs/validation/00-intro/philosophy.md	Added navigation links
docs/content/ToC.md	Removed legacy table of contents file
.agents/tasks/validation-documentation-plan.md	Added documentation planning file with absolute paths

Comments suppressed due to low confidence (2)

docs/content/docs/validation/08-custom-validation/_index.md:18

The image path uses ../.github/readme/ while the similar image reference in 09-developers-guide/architecture.md uses .github/readme/ (without the ../ prefix). Both files are at the same directory level, so they should use consistent path patterns. The inconsistency suggests one of these paths may not work correctly. Verify which pattern is correct for your Hugo configuration and make both files consistent.
.agents/tasks/validation-documentation-plan.md:68
This file contains absolute local file system paths that appear to be specific to a developer's machine (e.g., /Users/sanders/Projects/Spine/validation/). These paths should be converted to relative paths or removed from the committed documentation plan, as they won't work for other developers and could expose internal directory structures.

- Docs content (Hugo): `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/`
- Protobuf options reference (for built-ins):
  - `/Users/sanders/Projects/Spine/validation/docs/_options/options.proto`
  - `/Users/sanders/Projects/Spine/validation/docs/_options/time_options.proto`
- Example projects for embedded snippets: `/Users/sanders/Projects/Spine/validation/docs/_examples/`
- Docs build notes: `/Users/sanders/Projects/Spine/validation/docs/GRADLE.md`

## Definition of done (for a “first complete docs cut”)

- Navigation is consistent (no dead links between pages).
- Embedded code snippets are up-to-date (`checkSamples` passes).
- Preview site builds locally (`buildSite` succeeds).
- “Getting started” can be followed end-to-end without guessing.

## Minimal task list (in order)

1) Information architecture (IA): make Hugo navigation coherent
- Status: DONE (2026-02-23).
- Added/updated section landing pages:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/_index.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/_index.md`
- Replaced broken `.../index.md` links with directory links where appropriate:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/_index.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/_index.md`
- Added “What’s next” navigation to keep a clear reading path:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/target-audience.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/philosophy.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/architecture.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/key-modules.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/first-model.md`
- Fixed an obvious broken image reference:
  `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/08-custom-validation/_index.md`

2) Complete “Getting started” flow
- Validate that “Adding to build” + “First model” cover:
  importing options, build-time validation, `build()` vs `buildPartial()`, and `validate()`.

3) Concepts: explain how Validation works (one layer deeper than “getting started”)
- Add a Concepts landing page and an “options overview” page that explains:
  where options come from, how they’re applied, and what code gets generated.
- Keep this conceptual (no option-by-option details yet).

4) Built-in options: publish a minimal reference set
- From `/Users/sanders/Projects/Spine/validation/docs/_options/options.proto` and
  `/Users/sanders/Projects/Spine/validation/docs/_options/time_options.proto`,
  enumerate the built-in options and group them (fields, strings, numbers, collections, message-level, time).
- For each documented option: purpose, supported field types, common pitfalls, and a short `.proto` example.
- Start with the options already used in docs/examples: `(required)`, `(pattern)`, `(min)/(max)`,
  `(distinct)`, `(validate)`, `(when)`.

5) Runtime API usage (Java + Kotlin)
- Document the two primary usage patterns:
  - fail-fast on `build()` (throws `ValidationException`);
  - non-throwing `validate()` (returns `Optional<ValidationError>`).
- Link to the runtime entry points used by generated code:
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidatableMessage.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidatingBuilder.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/Validate.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidationException.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/kotlin/io/spine/validation/MessageExtensions.kt`.

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

Get the latest theme updates

Copilot

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

docs/content/docs/validation/08-custom-validation/_index.md:18

The image path ../.github/readme/typical_custom_option.jpg is incorrect. From the location docs/content/docs/validation/08-custom-validation/_index.md, this path would resolve to docs/content/docs/validation/.github/readme/typical_custom_option.jpg, but the actual file is at the repository root .github/readme/typical_custom_option.jpg. In Hugo documentation sites, you'll need to either copy the image to the appropriate content directory or use an absolute path from the site root (e.g., /.github/readme/typical_custom_option.jpg). Additionally, verify that the image format change from .png to .jpg is intentional and that the .jpg file exists.
.agents/tasks/validation-documentation-plan.md:68
This file contains absolute filesystem paths specific to a particular developer's machine (e.g., /Users/sanders/Projects/Spine/validation/). These paths should either be made relative or removed, as they will not work for other developers and could expose sensitive information about the development environment. Consider using relative paths from the repository root or removing absolute paths entirely from committed documentation.

- Docs content (Hugo): `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/`
- Protobuf options reference (for built-ins):
  - `/Users/sanders/Projects/Spine/validation/docs/_options/options.proto`
  - `/Users/sanders/Projects/Spine/validation/docs/_options/time_options.proto`
- Example projects for embedded snippets: `/Users/sanders/Projects/Spine/validation/docs/_examples/`
- Docs build notes: `/Users/sanders/Projects/Spine/validation/docs/GRADLE.md`

## Definition of done (for a “first complete docs cut”)

- Navigation is consistent (no dead links between pages).
- Embedded code snippets are up-to-date (`checkSamples` passes).
- Preview site builds locally (`buildSite` succeeds).
- “Getting started” can be followed end-to-end without guessing.

## Minimal task list (in order)

1) Information architecture (IA): make Hugo navigation coherent
- Status: DONE (2026-02-23).
- Added/updated section landing pages:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/_index.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/_index.md`
- Replaced broken `.../index.md` links with directory links where appropriate:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/_index.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/_index.md`
- Added “What’s next” navigation to keep a clear reading path:
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/target-audience.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/00-intro/philosophy.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/architecture.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/09-developers-guide/key-modules.md`
  - `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/01-getting-started/first-model.md`
- Fixed an obvious broken image reference:
  `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/08-custom-validation/_index.md`

2) Complete “Getting started” flow
- Validate that “Adding to build” + “First model” cover:
  importing options, build-time validation, `build()` vs `buildPartial()`, and `validate()`.

3) Concepts: explain how Validation works (one layer deeper than “getting started”)
- Add a Concepts landing page and an “options overview” page that explains:
  where options come from, how they’re applied, and what code gets generated.
- Keep this conceptual (no option-by-option details yet).

4) Built-in options: publish a minimal reference set
- From `/Users/sanders/Projects/Spine/validation/docs/_options/options.proto` and
  `/Users/sanders/Projects/Spine/validation/docs/_options/time_options.proto`,
  enumerate the built-in options and group them (fields, strings, numbers, collections, message-level, time).
- For each documented option: purpose, supported field types, common pitfalls, and a short `.proto` example.
- Start with the options already used in docs/examples: `(required)`, `(pattern)`, `(min)/(max)`,
  `(distinct)`, `(validate)`, `(when)`.

5) Runtime API usage (Java + Kotlin)
- Document the two primary usage patterns:
  - fail-fast on `build()` (throws `ValidationException`);
  - non-throwing `validate()` (returns `Optional<ValidationError>`).
- Link to the runtime entry points used by generated code:
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidatableMessage.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidatingBuilder.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/Validate.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/java/io/spine/validation/ValidationException.java`,
  `/Users/sanders/Projects/Spine/validation/jvm-runtime/src/main/kotlin/io/spine/validation/MessageExtensions.kt`.

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

Also: * Add sample tabs. * Remove the "Generated code" section.

Copilot

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

docs/content/docs/validation/00-intro/_index.md:124

Links within Hugo content are mixed between directory-style URLs and direct .md references. Given you’re switching other links to directory form (e.g., ../01-getting-started/), the .md links here are likely to render as broken URLs in the generated site. Prefer Hugo ref/relref (or directory-style links like target-audience/ and philosophy/) for consistency and to avoid 404s.

- [Target audience](target-audience.md)
- [Philosophy](philosophy.md)
- [Getting started](../01-getting-started/)

docs/content/docs/validation/01-getting-started/_index.md:15

These links mix directory-style (../00-intro/) with .md targets (target-audience.md, philosophy.md). If the site is intended to use pretty URLs (as implied by other edits), linking to .md will likely generate broken links on the rendered site. Use Hugo ref/relref (or ../00-intro/target-audience/ and ../00-intro/philosophy/) to keep URLs correct.

- Introduction → [Overview](../00-intro/)
- Who this is for → [Target audience](../00-intro/target-audience.md)
- Design principles → [Philosophy](../00-intro/philosophy.md)

.agents/tasks/validation-documentation-plan.md:14

This new repo-local plan hard-codes absolute local paths (/Users/sanders/...), which makes it non-portable for other contributors and CI environments. Replace these with repository-relative paths (e.g., docs/content/docs/validation/, docs/_options/..., docs/_examples/) so the plan remains accurate for all developers.

- Docs content (Hugo): `/Users/sanders/Projects/Spine/validation/docs/content/docs/validation/`
- Protobuf options reference (for built-ins):
  - `/Users/sanders/Projects/Spine/validation/docs/_options/options.proto`
  - `/Users/sanders/Projects/Spine/validation/docs/_options/time_options.proto`
- Example projects for embedded snippets: `/Users/sanders/Projects/Spine/validation/docs/_examples/`
- Docs build notes: `/Users/sanders/Projects/Spine/validation/docs/GRADLE.md`

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

docs/data/docs/validation/2-0-0-snapshot/sidenav.yml

Copilot

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

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

Fix the sidenav and update the theme

Copilot

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated no new comments.

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

Copilot

Pull request overview

Copilot reviewed 24 out of 28 changed files in this pull request and generated no new comments.

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

armiol

@alexander-yevsyukov LGTM except for a few comments.

armiol · 2026-02-25T18:17:32Z

docs/content/docs/validation/08-custom-validation/typical_custom_option.jpg

In this picture, in its top-right corner I would go with "JVM Validation plugin". Not "Java Validation Plugin".

docs/content/docs/validation/09-developers-guide/key-modules.md

alexander-yevsyukov added 10 commits February 23, 2026 20:16

Bump version -> 2.0.0-SNAPSHOT.397

a10f379

Add documentation plan file

5b2bf77

Remove temporary ToC and update the plan

ab82bf8

Address the first task from the plan

90f21e4

Add prefix for the developer's guide folder name

c63c041

Add prefix for the developer's guide folder name

8dfbe31

Transform custom validation text into a folder

b0fbaf6

Update the link in the plan

496cbce

Split first-model.md into phased pages

2369333

Simplify "Quick path" section

971b82d

Copilot AI review requested due to automatic review settings February 24, 2026 17:32

Copilot started reviewing on behalf of alexander-yevsyukov February 24, 2026 17:32 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

JuliaEvseeva and others added 4 commits February 24, 2026 18:44

Get the latest theme updates

64462bd

Merge pull request #268 from SpineEventEngine/get-theme-updates

b2f1a67

Get the latest theme updates

Get the latest theme updates

ed56404

Merge pull request #269 from SpineEventEngine/get-theme-updates

87d5926

Get the latest theme updates

Copilot AI review requested due to automatic review settings February 24, 2026 18:07

Copilot started reviewing on behalf of alexander-yevsyukov February 24, 2026 18:08 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

alexander-yevsyukov added 5 commits February 24, 2026 18:32

Add language name for console examples

64f4a8e

Add existing pages for sidebar

f5e386d

Bump version -> 2.0.0-SNAPSHOT.398

1ed9283

Update examples ref.

bfb5d42

Add front matter to the pages

9db6b2b

Also: * Add sample tabs. * Remove the "Generated code" section.

Copilot AI review requested due to automatic review settings February 24, 2026 19:25

Copilot AI reviewed Feb 24, 2026

View reviewed changes

docs/data/docs/validation/2-0-0-snapshot/sidenav.yml Show resolved Hide resolved

alexander-yevsyukov added 3 commits February 24, 2026 19:29

Update dependency reports

3ba05f9

Use the note block

f909ce7

Improve the text on standalone Validation plugin setup

2cd6bdc

JuliaEvseeva and others added 4 commits February 25, 2026 12:13

Fix the side-navigation key

5fa30ff

Add the link

8d91e0f

Use sentence capitalization in titles in front matter

85fbe62

Improve wording of "Using the generated code" section

596df41

Copilot AI review requested due to automatic review settings February 25, 2026 16:06

Copilot AI reviewed Feb 25, 2026

View reviewed changes

alexander-yevsyukov and others added 5 commits February 25, 2026 16:09

Remove irrelevant doc plan item

e7c3391

Mention usage in an anticorruption layer

be2b6e9

Get theme updates with the fix for relative URLs

893f6a6

Add empty Concepts section

97eee7f

Merge pull request #270 from SpineEventEngine/fix-sidenav

197a4b5

Fix the sidenav and update the theme

Copilot AI review requested due to automatic review settings February 25, 2026 16:58

Copilot AI reviewed Feb 25, 2026

View reviewed changes

alexander-yevsyukov added 6 commits February 25, 2026 17:07

Fix placement of pictures by sections

6a487d9

Update module list and clarify the purposes

e7ffef1

Make table headers come in bold

be4f91a

Replace "ProtoData" with "Compiler" on the diagram

15f1614

Replace "Policy" with "Reaction" in the docs

c13a83d

Replace "Policy" with "Reaction" in the docs

dd9e3bf

Copilot AI review requested due to automatic review settings February 25, 2026 18:00

Copilot AI reviewed Feb 25, 2026

View reviewed changes

alexander-yevsyukov self-assigned this Feb 25, 2026

alexander-yevsyukov requested a review from armiol February 25, 2026 18:09

armiol requested changes Feb 25, 2026

View reviewed changes

Improve section description

f128a97

alexander-yevsyukov requested a review from armiol February 25, 2026 18:32

alexander-yevsyukov enabled auto-merge February 25, 2026 18:32

armiol approved these changes Feb 25, 2026

View reviewed changes

alexander-yevsyukov merged commit fce5b89 into master Feb 25, 2026
8 checks passed

alexander-yevsyukov deleted the docs-set-4 branch February 25, 2026 18:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add text to "Getting started" documentation section#267

Add text to "Getting started" documentation section#267
alexander-yevsyukov merged 48 commits intomasterfrom
docs-set-4

alexander-yevsyukov commented Feb 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

armiol left a comment

Uh oh!

armiol Feb 25, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

alexander-yevsyukov commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes in details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

armiol left a comment

Choose a reason for hiding this comment

Uh oh!

armiol Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alexander-yevsyukov commented Feb 24, 2026 •

edited

Loading