Developers guide#293
Draft
alexander-yevsyukov wants to merge 28 commits intomasterfrom
Draft
Conversation
Also: * Use foot-note like links.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR primarily adds a contributor-facing Developer’s Guide for Spine Validation, restructures the docs tree around that new guide, and includes routine version/wrapper refreshes. It fits into the codebase as a documentation expansion for the published docs/validation site, with some accompanying release/build metadata updates.
Changes:
- Adds a new
06-developers-guidesection, removes the old09-developers-guidepages, and updates docs navigation/cross-links. - Refreshes top-level documentation (
README, intro pages, built-in-options references) and embed-code configuration for the new guide content. - Bumps snapshot/build metadata and updates the Gradle wrapper files.
Reviewed changes
Copilot reviewed 36 out of 41 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
version.gradle.kts |
Bumps the published Validation snapshot version. |
README.md |
Reworks overview text and replaces custom-validation details with a link. |
pom.xml |
Regenerates top-level version/dependency metadata. |
java-bundle/build.gradle.kts |
Updates copyright/header text. |
gradlew.bat |
Refreshes the Windows Gradle wrapper script. |
gradlew |
Updates the wrapper template source reference comment. |
gradle/wrapper/gradle-wrapper.properties |
Bumps the Gradle distribution and adds retry settings. |
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml |
Reorganizes docs navigation for the new Developer’s Guide. |
docs/content/docs/validation/09-developers-guide/key-modules.md |
Removes the old key-modules page. |
docs/content/docs/validation/09-developers-guide/architecture.md |
Removes the old architecture page. |
docs/content/docs/validation/09-developers-guide/_index.md |
Removes the old Developer’s Guide landing page. |
docs/content/docs/validation/06-developers-guide/validation-model.md |
Adds a detailed model internals page. |
docs/content/docs/validation/06-developers-guide/testing-strategy.md |
Adds a placeholder testing-strategy page. |
docs/content/docs/validation/06-developers-guide/runtime-library.md |
Adds a placeholder runtime-library page. |
docs/content/docs/validation/06-developers-guide/key-modules.md |
Adds the new key-modules page under the new guide path. |
docs/content/docs/validation/06-developers-guide/java-code-generation.md |
Adds a placeholder Java codegen page. |
docs/content/docs/validation/06-developers-guide/extension-points.md |
Adds a placeholder extension-points page. |
docs/content/docs/validation/06-developers-guide/build-and-release.md |
Adds a placeholder build/release page. |
docs/content/docs/validation/06-developers-guide/architecture.md |
Adds an expanded architecture deep dive. |
docs/content/docs/validation/06-developers-guide/adding-a-built-in-option.md |
Adds a placeholder contributor walkthrough page. |
docs/content/docs/validation/06-developers-guide/_index.md |
Adds the new Developer’s Guide landing page. |
docs/content/docs/validation/05-custom-validation/summary.md |
Updates next-step links to the new guide path. |
docs/content/docs/validation/05-custom-validation/pass-to-compiler.md |
Updates next-step links to the new guide path. |
docs/content/docs/validation/04-validators/implement-a-validator.md |
Updates next-step links to the new guide path. |
docs/content/docs/validation/04-validators/_index.md |
Updates next-step links to the new guide path. |
docs/content/docs/validation/03-built-in-options/_index.md |
Simplifies option source-of-truth linking. |
docs/content/docs/validation/01-getting-started/adding-to-build.md |
Updates the example plugin version. |
docs/content/docs/validation/00-intro/_index.md |
Expands the intro with “Why” and “How it works”. |
docs/content/docs/validation/_index.md |
Points the docs root at the new Developer’s Guide. |
docs/_settings/embed-code.yml |
Adds java and context source roots for embedded snippets. |
dependencies.md |
Refreshes the generated dependency report. |
context/src/main/kotlin/io/spine/tools/validation/ValidationPlugin.kt |
Adds an inline marker comment for docs snippet extraction. |
context/src/main/kotlin/io/spine/tools/validation/ErrorPlaceholder.kt |
Fixes KDoc punctuation/grammar. |
buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt |
Advances the internal Validation dependency constant. |
.agents/tasks/plan-writing-developers-guide.md |
Adds an internal plan for the Developer’s Guide rollout. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| echo location of your Java installation. 1>&2 | ||
|
|
||
| goto fail | ||
| "%COMSPEC%" /c exit 1 |
| echo location of your Java installation. 1>&2 | ||
|
|
||
| goto fail | ||
| "%COMSPEC%" /c exit 1 |
|
|
||
| It has access to the `Querying` interface and can query views to find those belonging | ||
| to the processed message type. | ||
| See the [Custom validation](docs/content/docs/validation/05-custom-validation/) section |
| --- | ||
| title: Overview and audience | ||
| description: Deep dive into Spine Validation architecture and internals. | ||
| headline: Documentation |
Comment on lines
+90
to
+94
| - page: 'The validation model in `:context`' | ||
| file_path: 06-developers-guide/validation-model | ||
| - page: 'Java code generation in `:java`' | ||
| file_path: 06-developers-guide/java-code-generation | ||
| - page: 'Runtime library `:jvm-runtime`' |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 36 out of 41 changed files in this pull request and generated 5 comments.
💡 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.414" | ||
| const val version = "2.0.0-SNAPSHOT.415" |
|
|
||
| It has access to the `Querying` interface and can query views to find those belonging | ||
| to the processed message type. | ||
| See the [Custom validation](docs/content/docs/validation/05-custom-validation/) section |
Comment on lines
+208
to
+211
| Several options exist purely to override an aspect of a primary option — `(if_missing)` | ||
| overrides the error message of `(required)`, `(if_invalid)` overrides `(validate)`, and | ||
| `(if_set_again)` overrides `(set_once)`. Each companion has its own reaction, its own | ||
| discovery event, and its data lands in the *primary*'s projection, not a separate one. |
| | `(goes)` | field<br>`GoesReaction`<br>`GoesFieldDiscovered`<br>`GoesField` | | ||
| | `(distinct)` | field<br>`DistinctReaction`<br>`DistinctFieldDiscovered`<br>`DistinctField` | | ||
| | `(if_has_duplicates)` | field<br>`IfHasDuplicatesReaction`<br>`IfHasDuplicatesOptionDiscovered`<br>`DistinctField` | | ||
| | `(validate)` | field<br>`ValidateReaction`<br>`ValidateFieldDiscovered`<br>`ValidateField` | |
Comment on lines
81
to
+89
| - page: Developer’s guide | ||
| key: 09-developers-guide | ||
| key: 06-developers-guide | ||
| children: | ||
| - page: Developer’s guide | ||
| file_path: 09-developers-guide | ||
| - page: Overview and audience | ||
| file_path: 06-developers-guide | ||
| - page: Architecture | ||
| file_path: 09-developers-guide/architecture | ||
| file_path: 06-developers-guide/architecture | ||
| - page: Key modules | ||
| file_path: 09-developers-guide/key-modules | ||
| file_path: 06-developers-guide/key-modules |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.