Developer's guide#293
Merged
alexander-yevsyukov merged 90 commits intomasterfrom May 7, 2026
Merged
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.
Avoid using `embed-code` in cases where it brings bigger blocks with all the API comments. We'll update the docs once SpineEventEngine/embed-code-go#20 is provided.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 45 out of 74 changed files in this pull request and generated 6 comments.
Comments suppressed due to low confidence (5)
docs/content/docs/validation/user/05-custom-validation/summary.md:46
- The Developer's Guide content now lives under
docs/content/docs/validation/developer/, but this link points to../06-developers-guide/which does not exist in the new structure. Update the relative link to the new developer guide entry point (e.g.,../../developer/overview-and-audience/).
docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md:76 - The Developer's Guide was moved under
docs/content/docs/validation/developer/, so../06-developers-guide/is an invalid target from this page. Update the link to the new developer guide entry point (e.g.,../../developer/overview-and-audience/).
docs/content/docs/validation/user/04-validators/implement-a-validator.md:141 - The Developer's Guide was moved under
docs/content/docs/validation/developer/, so this../06-developers-guide/link is broken. Update it to the new developer guide location (e.g.,../../developer/overview-and-audience/).
docs/content/docs/validation/user/04-validators/_index.md:112 - The Developer's Guide was moved under
docs/content/docs/validation/developer/, so this../06-developers-guide/link is broken. Update it to the new developer guide location (e.g.,../../developer/overview-and-audience/).
docs/content/docs/validation/user/03-built-in-options/_index.md:49 - There is a line containing only trailing whitespace here. Please remove it to avoid noisy diffs and keep markdown formatting clean.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Restore custom-option diagram or remove broken image link
This page embeds typical_custom_option.jpg, but the commit deletes docs/content/docs/validation/05-custom-validation/typical_custom_option.jpg and does not add the image at the new user/05-custom-validation/ location, so the rendered documentation will show a broken image.
ℹ️ 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".
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 73 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (4)
docs/content/docs/validation/user/05-custom-validation/summary.md:46
- These links point to
../06-developers-guide/..., but the Developer Guide content in this PR lives underdocs/content/docs/validation/developer/(and the Hugo sidenav usesdeveloper/...). As-is, these relative links will 404 in the rendered site. Update them to the new developer guide location (e.g.,../../developer/overview-and-audience/and the corresponding page paths).
docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md:76 - This "Developer's guide" link points to
../06-developers-guide/, but the developer guide was moved todocs/content/docs/validation/developer/in this PR. Update the relative link to the new location so the rendered docs don't contain a broken navigation link.
docs/content/docs/validation/user/04-validators/_index.md:112 - The "Developer's guide" link points to
../06-developers-guide/, but this PR’s developer guide lives underdocs/content/docs/validation/developer/. Update the link target to the new location to avoid a broken link in the rendered docs.
docs/content/docs/validation/user/04-validators/implement-a-validator.md:141 - The "Developer's guide" link points to
../06-developers-guide/, but this PR moves the developer guide underdocs/content/docs/validation/developer/. Update this link to the new path to avoid a broken link.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 73 changed files in this pull request and generated 5 comments.
Comments suppressed due to low confidence (4)
docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md:76
- This “What’s next” link points to
../06-developers-guide/, but there is nouser/06-developers-guidesection indocs/content/docs/validation/user/(the developer docs are underdocs/content/docs/validation/developer/). Update the link target to the new developer guide location (e.g.../../developer/overview-and-audience.mdor another intended entry page).
docs/content/docs/validation/user/04-validators/implement-a-validator.md:141 - This “What’s next” link points to
../06-developers-guide/, but the developer guide content was moved todocs/content/docs/validation/developer/. Update the link target to the new developer guide location (for example,../../developer/overview-and-audience.md).
docs/content/docs/validation/user/04-validators/_index.md:112 - This “What’s next” link points to
../06-developers-guide/, but there is no such section underdocs/content/docs/validation/user/. Update it to the new developer guide location underdocs/content/docs/validation/developer/(for example,../../developer/overview-and-audience.md).
docs/content/docs/validation/user/03-built-in-options/_index.md:49 - There is a line containing only whitespace before the link reference definition. This is easy to miss in reviews and can trigger whitespace-sensitive linters/formatters; please remove the trailing-whitespace-only line.
Comment on lines
48
to
56
| echo. 1>&2 | ||
| echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 | ||
| echo. 1>&2 | ||
| echo Please set the JAVA_HOME variable in your environment to match the 1>&2 | ||
| echo location of your Java installation. 1>&2 | ||
|
|
||
| goto fail | ||
| "%COMSPEC%" /c exit 1 | ||
|
|
||
| :findJavaFromJavaHome |
Comment on lines
62
to
69
| echo. 1>&2 | ||
| echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 | ||
| echo. 1>&2 | ||
| echo Please set the JAVA_HOME variable in your environment to match the 1>&2 | ||
| echo location of your Java installation. 1>&2 | ||
|
|
||
| goto fail | ||
| "%COMSPEC%" /c exit 1 | ||
|
|
| * The version of the Validation library artifacts. | ||
| */ | ||
| const val version = "2.0.0-SNAPSHOT.414" | ||
| const val version = "2.0.0-SNAPSHOT.415" |
Comment on lines
60
to
67
| <scope>compile</scope> | ||
| </dependency> | ||
| <dependency> | ||
| <groupId>io.spine</groupId> | ||
| <artifactId>spine-validation-jvm-runtime</artifactId> | ||
| <version>2.0.0-SNAPSHOT.414</version> | ||
| <version>2.0.0-SNAPSHOT.415</version> | ||
| <scope>compile</scope> | ||
| </dependency> |
Comment on lines
289
to
294
| <dependency> | ||
| <groupId>io.spine.tools</groupId> | ||
| <artifactId>validation-java-bundle</artifactId> | ||
| <version>2.0.0-SNAPSHOT.414</version> | ||
| <version>2.0.0-SNAPSHOT.415</version> | ||
| </dependency> | ||
| <dependency> |
Collaborator
Author
|
@armiol, it accidentally merged because of misconfiguration of the branch rule settings. I'll undo the PR, and create a new one. |
This was referenced May 7, 2026
alexander-yevsyukov
added a commit
that referenced
this pull request
May 8, 2026
Revert PR #293 (accidentally merged)
alexander-yevsyukov
added a commit
that referenced
this pull request
May 8, 2026
Re-apply PR #293 (Developer's guide)
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.
This PR adds the “Validation developer guide” to the documentation. The navigation of the preview site was changed so that "User guide" and "Developer guide" appear as top-level nodes on the left side panel. This, in turn, required having
useranddevelopersubdirectories underdocs/validation/.This PR also includes latest updates from
site-commonsthat bring improved table styes and page level navigation on the right.Other notable changes
/writerskill was updated to use typographic quotes when referencing sections and pages in the text body.embed-code.ymlwas updated with therootcode path,code-includesparameter was also added to avoid copying files under.git/which failed the build. It will also make the embedding work a bit faster because we won't copy anything but embedded content candidates.