Add initial Validation library documentation with Hugo preview infrastructure#261
Add initial Validation library documentation with Hugo preview infrastructure#261alexander-yevsyukov merged 127 commits intomasterfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates project documentation by replacing informal "Please note" phrases with more concise "Note that" phrasing, and bumps version numbers across multiple configuration files and documentation.
Changes:
- Simplified documentation language by removing "Please" prefix from note statements
- Updated version from 2.0.0-SNAPSHOT.393 to 2.0.0-SNAPSHOT.394 across configuration files
- Updated dependency versions (CoreJvmCompiler from .050 to .051, validation-jvm-runtime from .392 to .393)
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| version.gradle.kts | Bumped validation version to .394 |
| tests/consumer/src/test/kotlin/io/spine/validation/test/CurrencyOptionITest.kt | Removed "Please" from documentation note |
| pom.xml | Updated project version to .394 and dependency versions |
| jvm-runtime/src/main/kotlin/io/spine/validation/MessageValidator.kt | Simplified "Please note" to "Note" in KDoc |
| java/src/main/kotlin/io/spine/tools/validation/java/setonce/SetOnceEnumField.kt | Condensed and simplified documentation note |
| java/src/main/kotlin/io/spine/tools/validation/java/setonce/SetOnceBytesField.kt | Condensed and simplified documentation note |
| java/src/main/kotlin/io/spine/tools/validation/java/JavaValidationPlugin.kt | Reformatted multi-line KDoc note for clarity |
| docs/01-getting-started/index.md | Improved line wrapping for better readability |
| dependencies.md | Updated version references and generation timestamps |
| config | Updated subproject commit reference |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt | Updated validation version constant to .393 |
| buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt | Updated CoreJvmCompiler versions to .051 |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Also: * Update the reference to Jakarta Validation, addressing the recent name change.
Also: * Update Kotlin requirement to 2.2.21+.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (2)
docs/options.proto:1
- Corrected spelling of 'please' to 'use' for consistency with the PR's goal of removing informal language like 'Please' from comments.
/*
docs/ToC.md:1
- These link text entries still use title case capitalization ("First Validated Model", "Validation Workflow") while other entries in the same file have been updated to sentence case. These should be changed to "Your first validated model" and "Validation workflow" for consistency.
# Spine Validation — Table of contents
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 72 out of 81 changed files in this pull request and generated no new comments.
Files not reviewed (2)
- .idea/inspectionProfiles/Project_Default.xml: Language not supported
- docs/_preview/package-lock.json: Language not supported
Comments suppressed due to low confidence (8)
pom.xml:1
protobuf-gradle-pluginis a Gradle plugin artifact and generally shouldn’t be published as a regular Maven compile dependency of this project (it will leak into consumers’ classpaths without being useful at runtime). If the goal is to support the Gradle plugin module, keep this dependency in the Gradle plugin’s build only (Gradle buildscript/plugin classpath), and remove it from the Maven POM dependencies.
docs/_code/first-model/src/main/proto/spine/validation/docs/first_model/bank_card.proto:1- The regex is not anchored at the end, so it will accept strings that start with a valid-looking number but have trailing characters (despite the comment saying it must match a 16-digit number formatted exactly). Consider adding an end anchor (
$) so the whole field value must match.
docs/go.mod:1 - Consider using the canonical
godirective format (go 1.22) and keeping it consistent with the preview module’sgo.mod. Using patch versions in thegodirective can reduce compatibility with tooling and makes it harder to keep the docs toolchain aligned.
docs/_preview/go.mod:1 - The preview site’s Go version is significantly different from the docs module’s Go version and uses a patch-level directive. Aligning the Go version across
docs/go.modanddocs/_preview/go.mod(and using the canonicalgo 1.xxformat) will make Hugo Module builds more reproducible across developers/CI.
settings.gradle.kts:1 - This
include(...)list uses:-prefixed project paths for other modules, butdocsis added without the prefix. For consistency (and to avoid ambiguity in multi-project naming), consider using":docs"here.
docs/content/docs/validation/01-getting-started/adding-to-build.md:1 - Correct the grammar: “base on” → “based on”.
docs/_script/install-dependencies:1 - Sourcing user shell init files from a build script makes builds non-reproducible and can unexpectedly execute arbitrary code (especially in CI runners or shared environments). Prefer explicitly setting required env vars in the Gradle task/CI, or at least make this opt-in (e.g., behind a flag) and quote variable expansions when checking/reading paths.
docs/_script/embed-code:1 embed-codeis hardcoded to the macOS binary, whilecheck-samplesselects the tool based on environment. Consider adding the same OS/CI detection here (or delegating to a shared helper) so the embedding task can run on Linux as well when needed.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Get theme updates and update the version configuration
|
@copilot, update the description of this PR analyzing all commits made from the very beginning of the PR. Drop the description of the "Please" changes in the documentation. They are not essential to the PR. Consider having at least 3 sections:
|
|
@alexander-yevsyukov I've opened a new pull request, #264, to work on those changes. Once the pull request is ready, I'll request review from you. |
alexander-yevsyukov
changed the title
![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
Here are some automated review suggestions for this pull request.
Reviewed commit: bc5fd0a5b2
ℹ️ 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".
| else | ||
| echo "Running locally on macOS." | ||
| TOOL="./embed-code-macos" |
There was a problem hiding this comment.
When :docs:checkSamples runs on Linux outside GitHub Actions (for example, local Linux dev machines or non-GHA CI), the else branch hard-codes embed-code-macos, which fails with Exec format error instead of checking samples. This makes the task unusable in those environments unless GITHUB_ACTIONS=true is injected, so the script should choose the binary from the actual platform rather than the CI vendor flag.
Useful? React with 👍 / 👎.
| cd _bin | ||
|
|
||
| # Update code samples. | ||
| ./embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed" |
There was a problem hiding this comment.
The embed workflow always invokes ./embed-code-macos, so :docs:embedCode cannot run on Linux hosts and exits with Exec format error. Because this task is the path for regenerating embedded snippets, Linux contributors/automation cannot update docs unless they manually patch the script each time.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 72 out of 81 changed files in this pull request and generated no new comments.
Files not reviewed (2)
- .idea/inspectionProfiles/Project_Default.xml: Language not supported
- docs/_preview/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 71 out of 80 changed files in this pull request and generated 2 comments.
Files not reviewed (2)
- .idea/inspectionProfiles/Project_Default.xml: Language not supported
- docs/_preview/package-lock.json: Language not supported
Comments suppressed due to low confidence (7)
pom.xml:1
- The project version is bumped to
2.0.0-SNAPSHOT.394, but dependencies onspine-validation-jvm-runtimeandvalidation-java-bundleare set to2.0.0-SNAPSHOT.393. If this POM is meant to represent a consistent set of artifacts for394, these versions should be aligned (or explicitly explained/managed via a property/BOM).
pom.xml:1 - The project version is bumped to
2.0.0-SNAPSHOT.394, but dependencies onspine-validation-jvm-runtimeandvalidation-java-bundleare set to2.0.0-SNAPSHOT.393. If this POM is meant to represent a consistent set of artifacts for394, these versions should be aligned (or explicitly explained/managed via a property/BOM).
pom.xml:1 - The project version is bumped to
2.0.0-SNAPSHOT.394, but dependencies onspine-validation-jvm-runtimeandvalidation-java-bundleare set to2.0.0-SNAPSHOT.393. If this POM is meant to represent a consistent set of artifacts for394, these versions should be aligned (or explicitly explained/managed via a property/BOM).
docs/content/docs/validation/01-getting-started/adding-to-build.md:1 - Correct grammar: change “base on” to “based on”.
docs/_script/embed-code:1 - This script hardcodes the macOS binary, which will fail on Linux/Windows (including many developer environments). Consider selecting the binary based on OS (similar to
check-samples) or invoking a single platform-appropriate wrapper.
docs/_script/install-dependencies:1 - This script doesn’t enable “fail fast” mode. Since it performs
cd _previewand runsnpm install, failures can be silently ignored and subsequent commands may execute in the wrong directory. Addset -e(ideallyset -euo pipefail) near the top; the same applies tohugo-buildandhugo-serve.
docs/_options/options.proto:1 - Typo in documentation: “weather” should be “whether”.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| private fun updatePluginVersion(file: File, id: String, version: String) { | ||
| val content = file.readText() | ||
| // Regex to match: id("plugin-id") version "version-number" | ||
| val regex = """id\("$id"\)\s+version\s+"([^"]+)"""".toRegex() | ||
|
|
||
| if (regex.containsMatchIn(content)) { | ||
| val updatedContent = regex.replace(content) { | ||
| "id(\"$id\") version \"$version\"" |
There was a problem hiding this comment.
The plugin id is interpolated directly into a regex pattern; since plugin IDs commonly contain dots (.), they will be treated as “any character” and can match/replace the wrong plugin declaration. Escape the id when building the regex (e.g., via Regex.escape(id)).
| .redirectError(errorOut) | ||
| .redirectOutput(debugOut) | ||
| .start() | ||
| System.err.println("[RunGradle] Running the command: '${command.joinToString(" ")}'." + |
There was a problem hiding this comment.
Using System.err.println in a Gradle task produces unstructured output and ignores Gradle log levels. Prefer logger.lifecycle(...) / logger.info(...) (and/or guard under a debug flag) so CI logs stay clean and users can control verbosity.
| System.err.println("[RunGradle] Running the command: '${command.joinToString(" ")}'." + | |
| logger.lifecycle("[RunGradle] Running the command: '${command.joinToString(" ")}'." + |
This PR establishes the documentation foundation for the Validation library, including a Hugo-based preview system, working code examples, and initial user-facing content.
Main code changes
Base.libfromimplementationtoapiscope injvm-runtimemoduleTIMEOUT_MINUTESproperty for long-running CI tasks, bumped Gradle to 9.3.1Documentation infrastructure
docs/as first-class Gradle module with Go module support and Hugo theme integrationUpdatePluginVersiontask maintains version consistency across documentation examples_code/projectsfirst-model: Basic validation withBankCardmessage demonstrating(required)and(pattern)constraintsfirst-model-with-framework: Validation integrated with Spine frameworkDocumentation content
BankCardexample with regex patterns for card numbers and owner names