From 7568a5153c3163bfcf97bc5fe5e5a050bd0ab42a Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 16:29:59 +0100 Subject: [PATCH 01/40] Use HTTPS in (c) header --- docs/build.gradle.kts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build.gradle.kts b/docs/build.gradle.kts index 5d8c984a31..c652ba5682 100644 --- a/docs/build.gradle.kts +++ b/docs/build.gradle.kts @@ -5,7 +5,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * https://www.apache.org/licenses/LICENSE-2.0 * * Redistribution and use in source and/or binary forms, with or without * modification, must retain the above copyright notice and the following From 3d3885f08810a82018d3bcacab73133a68382342 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 16:39:20 +0100 Subject: [PATCH 02/40] Bump version -> `2.0.0-SNAPSHOT.419` --- version.gradle.kts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version.gradle.kts b/version.gradle.kts index 2672854e00..aae97b27a8 100644 --- a/version.gradle.kts +++ b/version.gradle.kts @@ -27,4 +27,4 @@ /** * The version of the Validation library to publish. */ -val validationVersion by extra("2.0.0-SNAPSHOT.418") +val validationVersion by extra("2.0.0-SNAPSHOT.419") From 9e5663d11ea4d38eab8cdc6e434f969cd0859f71 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 16:39:46 +0100 Subject: [PATCH 03/40] Bump Validation -> `2.0.0-SNAPSHOT.419` --- docs/_examples | 2 +- docs/content/docs/validation/developer/build-and-release.md | 2 +- .../docs/validation/user/01-getting-started/adding-to-build.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_examples b/docs/_examples index 4d5a45bc1b..cb986af5d7 160000 --- a/docs/_examples +++ b/docs/_examples @@ -1 +1 @@ -Subproject commit 4d5a45bc1b62a7f7a640e3782b572c2ee66135c4 +Subproject commit cb986af5d7a72ee58c1d73a3e50e4dae1a90c4d3 diff --git a/docs/content/docs/validation/developer/build-and-release.md b/docs/content/docs/validation/developer/build-and-release.md index 87c8cccd21..88c7ff12f1 100644 --- a/docs/content/docs/validation/developer/build-and-release.md +++ b/docs/content/docs/validation/developer/build-and-release.md @@ -47,7 +47,7 @@ through Gradle's `extra` properties: end="val validationVersion"> ```kotlin -val validationVersion by extra("2.0.0-SNAPSHOT.418") +val validationVersion by extra("2.0.0-SNAPSHOT.419") ``` The root build script applies this file under `allprojects { … }` and assigns diff --git a/docs/content/docs/validation/user/01-getting-started/adding-to-build.md b/docs/content/docs/validation/user/01-getting-started/adding-to-build.md index 40094039a8..fad7d89420 100644 --- a/docs/content/docs/validation/user/01-getting-started/adding-to-build.md +++ b/docs/content/docs/validation/user/01-getting-started/adding-to-build.md @@ -90,7 +90,7 @@ Add the Validation plugin to the build. ```kotlin plugins { module - id("io.spine.validation") version "2.0.0-SNAPSHOT.418" + id("io.spine.validation") version "2.0.0-SNAPSHOT.419" } ``` From 490ae09bd2e78cc01f6cbc954de1c8cca25e28a2 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 17:00:43 +0100 Subject: [PATCH 04/40] Add Kotlin files to `.gitattributes` --- .gitattributes | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitattributes b/.gitattributes index 810ea7ffd9..84a8f15676 100644 --- a/.gitattributes +++ b/.gitattributes @@ -24,6 +24,10 @@ LICENSE text # Java sources *.java text +# Kotlin sources +*.kt text +*.kts text + # Python sources *.py text From 378f7126e1dbd3d9faa99d26eaf51e0dd129646e Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 17:36:51 +0100 Subject: [PATCH 05/40] Draft the plan for extending documentation --- .agents/tasks/describe-documentation-plan.md | 41 ++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .agents/tasks/describe-documentation-plan.md diff --git a/.agents/tasks/describe-documentation-plan.md b/.agents/tasks/describe-documentation-plan.md new file mode 100644 index 0000000000..59215fe18e --- /dev/null +++ b/.agents/tasks/describe-documentation-plan.md @@ -0,0 +1,41 @@ +# Task: Describe the technical details of the documentation process + +## Content that we know needs to be there +- Description of the `docs` module and its purpose. +- Brief explanation that we use Hugo, the `_preview` directory and how the `docs` module + is going to be used when building the documentation section of the spine.io website. +- Explanation of the build tasks defined in `docs/build.gradle.kts` and their purposes. + Use `docs/GRADLE.md` as a reference or even text source for this section. +- Explanation of the paths used in the scripts and how to work with them. +- Description of how the example sources are included in the documentation project. +- Explanation of using Spine Time as an implementaiton example and that the library is added as GitModule because of this. +- Documentation of `settings/embed-code.yml` file and source roots under it. + + +## Procedures to be documented + +### Incrementing the version of Validation +1. Update the version in `version.gradle.kts` file. +2. Run `./gradlew :docs:updatePluginVersions` to update the version of Validation Graldle plugin + in the examples and files documentation. +3. Commit the change to `version.gradle.kts` file using the commit message + ```text + Bump version -> `` + ``` +4. Commit the change to the remaining files using the commit message + ```text + Bump Validation -> `` + ``` +5. Run `./gradlew clean build` and commit `pom.xml` and `dependencies.md` using the commit + message `Update dependency reports` as usually when incrementing the version in + Spine SDK projects. + +### Updating the version of the CoreJvm Compiler +1. Update the version in the dependency object `CoreJvmCompiler` under `buildSrc`. +2. Run `./gradlew :docs:updatePluginVersions` to update the version of CoreJvm Graldle plugin + in the examples and files documentation. + +## Tasks that are known to be done +- [ ] Add `docs/README.md` file with the brief description, and the link to + the page under the `content` directory that explains the documentation process in more detail. + Remove `GRADLE.md` file as no longer needed after that. From 506bed5d4114f420b906af908f748ced7b5675bb Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:01:06 +0100 Subject: [PATCH 06/40] Rename the plan file --- ...plan.md => describe-documentation-plan-draft.md} | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) rename .agents/tasks/{describe-documentation-plan.md => describe-documentation-plan-draft.md} (77%) diff --git a/.agents/tasks/describe-documentation-plan.md b/.agents/tasks/describe-documentation-plan-draft.md similarity index 77% rename from .agents/tasks/describe-documentation-plan.md rename to .agents/tasks/describe-documentation-plan-draft.md index 59215fe18e..a921e71c25 100644 --- a/.agents/tasks/describe-documentation-plan.md +++ b/.agents/tasks/describe-documentation-plan-draft.md @@ -1,5 +1,9 @@ # Task: Describe the technical details of the documentation process +## Goal +- Create a comprehensive documentation that describes the technical details of the documentation + process for the Spine Validation library. + ## Content that we know needs to be there - Description of the `docs` module and its purpose. - Brief explanation that we use Hugo, the `_preview` directory and how the `docs` module @@ -11,9 +15,11 @@ - Explanation of using Spine Time as an implementaiton example and that the library is added as GitModule because of this. - Documentation of `settings/embed-code.yml` file and source roots under it. - ## Procedures to be documented +The sections below describe what procedures should be documented. +This is not an exhaustive list, but it includes the most important ones that are known at the moment. + ### Incrementing the version of Validation 1. Update the version in `version.gradle.kts` file. 2. Run `./gradlew :docs:updatePluginVersions` to update the version of Validation Graldle plugin @@ -39,3 +45,8 @@ - [ ] Add `docs/README.md` file with the brief description, and the link to the page under the `content` directory that explains the documentation process in more detail. Remove `GRADLE.md` file as no longer needed after that. + +## Placement of the documentation in the navigation +- The documentation about the documentation process should be placed in the `content` + directory under `docs/validation/developer/documentation.md` file. +- It should be the last item in the `Developer` section of the documentation. From ec2320f0a4354df1a0c2518ee6d3b02b35c7b50c Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:13:33 +0100 Subject: [PATCH 07/40] Refine the documentation2 plan --- .agents/tasks/describe-documentation-plan.md | 189 +++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 .agents/tasks/describe-documentation-plan.md diff --git a/.agents/tasks/describe-documentation-plan.md b/.agents/tasks/describe-documentation-plan.md new file mode 100644 index 0000000000..3fa4f7c9fa --- /dev/null +++ b/.agents/tasks/describe-documentation-plan.md @@ -0,0 +1,189 @@ +# Plan: Describe the technical details of the documentation process + +This plan elaborates the brief in +[`describe-documentation-plan-draft.md`](describe-documentation-plan-draft.md). +The goal is to deliver a dedicated documentation sub-tree under the existing +Developer guide that explains, end to end, how the Spine Validation +documentation is authored, built, previewed, and released. + +## 1. Outcome + +A new sub-tree appears as the last item of the "Validation developer guide" +section of the documentation and answers the following questions: + +- What is the `docs` module and how does it fit into the `spine.io` website + build? +- How is the documentation built locally and previewed? +- Which Gradle tasks are involved, what do they do, and where do their outputs + land? +- How are source code examples embedded into the documentation, and why is + Spine Time wired in as a Git submodule? +- How is `settings/embed-code.yml` structured, and what are the source roots? +- How do contributors perform the recurring documentation-related procedures + (version bumps, tool updates, submodule refresh, adding pages, adding + embedded examples)? + +In addition, `docs/README.md` is introduced as the in-repo entry point, and +`docs/GRADLE.md` is retired because its content is folded into the new pages. + +## 2. Deliverables + +### 2.1 New documentation sub-tree + +Location: +`docs/content/docs/validation/developer/documentation/` + +Pages: + +- `_index.md` — Overview. Purpose of the `docs` module; relationship to Hugo + and the `_preview` directory; how the module participates in the `spine.io` + website build; reading map for the child pages. +- `build-tasks.md` — Gradle build tasks defined in `docs/build.gradle.kts`, + what each task does, dependencies between them, and the paths the scripts + rely on. Folds in the content of `docs/GRADLE.md`. Covers `:docs:runSite` + (local Hugo preview) and the task that produces the publishable output. +- `embedded-examples.md` — How example sources are included in the + documentation; the role of Spine Time as the implementation-example library + and the rationale for wiring it as a Git submodule under `_time`; structure + of `settings/embed-code.yml` and its source roots. +- `tooling.md` — External tooling the docs build depends on: + - `site-commons` (Go module) — what it provides, why it is a Go module, how + it is consumed. + - `embed-code-go` — what it does, how it is consumed by the docs build. +- `procedures.md` — Step-by-step recipes for recurring tasks (see section 3). + +### 2.2 In-repo entry point and cleanup + +- Add `docs/README.md` with a brief description of the `docs` module and a + link to the new overview page (`developer/documentation/_index.md`). +- Remove `docs/GRADLE.md` once its content has been migrated into + `developer/documentation/build-tasks.md`. Verify there are no remaining + references to `GRADLE.md` before deletion. + +### 2.3 Navigation update + +- Update `docs/data/docs/validation/2-0-0-snapshot/sidenav.yml`: add a nested + entry as the last item under the `developer` key. Use `file_path` values + relative to the version `content_path` (`docs/validation`), without the + `.md` suffix, and treating `_index.md` as the directory path. Preserve the + file's existing ordering, indentation, quoting style, and comments. + +Proposed entry (final wording to be confirmed when drafting): + +```yaml +- page: Documentation process + key: documentation + children: + - page: Overview + file_path: developer/documentation + - page: Build tasks + file_path: developer/documentation/build-tasks + - page: Embedded examples + file_path: developer/documentation/embedded-examples + - page: External tooling + file_path: developer/documentation/tooling + - page: Procedures + file_path: developer/documentation/procedures +``` + +## 3. Procedures to document on `procedures.md` + +Each procedure is presented as numbered steps with the exact commands, the +files touched, and the expected outcome. + +1. **Incrementing the version of Validation** — as drafted in the brief + (update `version.gradle.kts`, run `:docs:updatePluginVersions`, commit + sequence, run `clean build`, commit `pom.xml` and `dependencies.md` as + `Update dependency reports`). +2. **Updating the version of the CoreJvm Compiler** — update the + `CoreJvmCompiler` dependency object under `buildSrc`, run + `:docs:updatePluginVersions`. +3. **Refreshing the embedded example sources from Spine Time** — initial + submodule init/update for `_time`, switching to a specific commit, and how + the change propagates through the embed-code pipeline. +4. **Adding a new embedded code example** — declare or extend a source root + in `settings/embed-code.yml`, reference the snippet from a Markdown page, + verify it renders in preview. +5. **Adding or updating a documentation page** — create the Markdown file + under `content/docs/validation/...`, update the corresponding + `sidenav.yml` entry, preview locally, validate links. +6. **Updating `site-commons`** — bump the Go module version in `go.mod`, + tidy/vendor as required, verify the preview still renders correctly. +7. **Updating `embed-code-go`** — bump the tool version, re-run the embed + pipeline, verify embedded snippets. +8. **Building the documentation locally** — which Gradle task produces the + publishable output, where the output lands, and how it is consumed by the + `spine.io` website build. +9. **Previewing the documentation locally** — `:docs:runSite`, prerequisites, + how to reach the preview, troubleshooting tips. + +## 4. Cross-cutting content notes + +- Use fenced code blocks for every shell command and file path. Format file + and directory names as inline code. +- Follow `.agents/documentation-guidelines.md` for quotation style, footnote + links for external `https://` URLs, and widow/runt/orphan/river handling. +- Match identifiers (Gradle task names, Kotlin/Go module names, YAML keys) to + what is in the repository at the time of writing. +- Prefer concrete, executable steps and short paragraphs over abstract + description. + +## 5. Research items to verify before writing + +These must be confirmed against the current repo state during drafting: + +- Exact set and names of Gradle tasks defined in `docs/build.gradle.kts` + (including `:docs:runSite`, `:docs:updatePluginVersions`, and the build + task that produces the publishable output) and their inter-task + dependencies. +- Output directory of the documentation build and how/where the `spine.io` + website pipeline consumes it. +- Current contents and source-root structure of + `docs/_settings/embed-code.yml`. +- The exact role of the `_preview` directory in the local Hugo preview flow + (input/output, generated vs. checked-in). +- How `_time` is wired as a Git submodule (path, default branch/commit + policy) and which Gradle tasks consume it. +- Whether `site-commons` is consumed via `go.mod` directly under `docs/`, + via a Hugo module config, or both. +- Current means of pinning the `embed-code-go` version used by the build. +- The version selector for the documentation site (the `2-0-0-snapshot` + versus `2-0-x` entries in `docs/data/versions.yml`) to confirm the + sub-tree is added to the main version only. + +## 6. Work breakdown + +Ordered for incremental review: + +1. **Discovery pass.** Walk the repo and answer every research item in + section 5. Capture findings as notes (not committed) to feed the drafts. +2. **Skeleton commit.** Create empty `_index.md`, `build-tasks.md`, + `embedded-examples.md`, `tooling.md`, `procedures.md` with frontmatter + and section headings only. Update `sidenav.yml` with the new entry. + Verify the navigation renders via `:docs:runSite`. +3. **Draft `_index.md`** (overview) and `build-tasks.md` (migrate + `GRADLE.md` content; expand with task descriptions, paths, and outputs). +4. **Draft `embedded-examples.md`** (Spine Time submodule rationale, + `embed-code.yml` structure, page-side syntax for embedding snippets). +5. **Draft `tooling.md`** (`site-commons`, `embed-code-go`: purpose, + consumption, update mechanics — pure description here; the update steps + live in `procedures.md`). +6. **Draft `procedures.md`** covering all nine procedures with verified + commands and expected outcomes. +7. **Add `docs/README.md`** pointing to `_index.md`; remove `docs/GRADLE.md` + after confirming no remaining references. +8. **Validation pass.** + - `./gradlew :docs:runSite` and click through every new page; verify + navigation, code blocks, embedded snippets, and internal links. + - Run `./gradlew dokka` if any Kotlin/Java source comments were touched. + - Re-read each page for adherence to the documentation guidelines + (quotation rules, reference-style external links, no widows/runts). + +## 7. Out of scope + +- Changes to historical doc versions (`2-0-x` and earlier) or their + `sidenav.yml` files. +- Documenting unrelated developer procedures not part of the documentation + pipeline. +- Restructuring the existing Developer guide pages beyond appending the new + sub-tree. From f611c48db6878b260178476c10e23e302211d33c Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:19:39 +0100 Subject: [PATCH 08/40] Update the doc2 plan with discovery findings --- .agents/tasks/describe-documentation-plan.md | 134 ++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) diff --git a/.agents/tasks/describe-documentation-plan.md b/.agents/tasks/describe-documentation-plan.md index 3fa4f7c9fa..ecce2c8032 100644 --- a/.agents/tasks/describe-documentation-plan.md +++ b/.agents/tasks/describe-documentation-plan.md @@ -179,7 +179,139 @@ Ordered for incremental review: - Re-read each page for adherence to the documentation guidelines (quotation rules, reference-style external links, no widows/runts). -## 7. Out of scope +## 7. Discovery findings + +Captured 2026-05-11 from the current `master`-tracking working tree. Use as +the factual basis for drafting; re-verify if the repo state changes. + +### 7.1 Gradle tasks defined in `docs/build.gradle.kts` + +All tasks are registered on the `:docs` project. Inter-task dependencies in +parentheses. + +| Task | Type | Purpose | +|-------------------------------|--------|------------------------------------------------------------------------------------------------| +| `updateValidationPluginVersion` | `UpdatePluginVersion` | Rewrites `id("io.spine.validation") version "…"` in every `build.gradle.kts` under `_examples/` to `validationVersion` from `version.gradle.kts`. Also updates `kotlin("…") version "…"` to `Kotlin.version`. | +| `updateCoreJvmPluginVersion` | `UpdatePluginVersion` | Same mechanism for `io.spine.core-jvm`, using `CoreJvmCompiler.version` from `buildSrc`. | +| `updatePluginVersions` | aggregate | Depends on the two tasks above. | +| `installDependencies` | `Exec` | Runs `_script/install-dependencies` → `npm install` inside `_preview/`. Not meant to be run manually. | +| `runSite` | `Exec` | Runs `_script/hugo-serve` → `hugo server` inside `_preview/`. Local preview. Depends on `installDependencies`. | +| `buildSite` | `Exec` | Runs `_script/hugo-build` → `hugo` inside `_preview/`. Builds the static site. Depends on `installDependencies`. | +| `embedCode` | `Exec` | Runs `_script/embed-code` (does `git submodule update --remote --merge --recursive`, then `_bin/embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed"`). Depends on `updatePluginVersions`. Manual use. | +| `checkSamples` | `Exec` | Runs `_script/check-samples` (uses `embed-code-linux` under GitHub Actions, `embed-code-macos` locally; `-mode="check"`). Depends on `updatePluginVersions`. Executed by `.github/workflows/check-code-embedding.yml`. | +| `publishAllToMavenLocal` | aggregate | Depends on every `PublishToMavenLocal` task across the root project's allprojects. | +| `buildExamples` | `RunGradle` | Runs `buildAll` inside `_examples/`. Depends on `publishAllToMavenLocal` and `updatePluginVersions`. | +| `buildAll` | aggregate | Depends on `publishAllToMavenLocal` and `buildExamples`. Used by `.github/workflows/check-code-embedding.yml`. | + +The `UpdatePluginVersion` task type is defined at +`buildSrc/src/main/kotlin/io/spine/gradle/docs/UpdatePluginVersion.kt`. + +### 7.2 Build output and `spine.io` handoff + +- `buildSite` writes Hugo output to `docs/_preview/public/` (Hugo's default + for the `_preview` working directory). +- `docs/GRADLE.md` states that the preview site is **not** meant to be + published as-is. The content of the `docs` module is merged into the main + documentation project at https://github.com/SpineEventEngine/documentation + for publication on `spine.io`. +- There is no workflow in `.github/workflows/` that deploys the preview + output. CI only exercises `:docs:buildAll` and `:docs:checkSamples` + (see `.github/workflows/check-code-embedding.yml`). + +### 7.3 `_preview` directory role + +- `_preview` is the Hugo project root for local preview. +- `_preview/hugo.toml` imports two Hugo modules: + - `../..` — the `docs/` module itself (provides `content/`, `data/`, + `layouts/`). + - `github.com/SpineEventEngine/site-commons` — the shared site theme/layout. +- `_preview/go.mod` pins both `site-commons` (currently + `v0.0.0-20260507130158-84db050dfe11`) and + `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`. +- `_preview/package.json` declares Node devDependencies (`postcss`, + `autoprefixer`, `@fullhuman/postcss-purgecss`, etc.) installed by + `npm install` via `installDependencies`. +- `_preview/public/` holds the generated static site (`docs/`, `index.html`, + `css`/`js`/`img` assets, sitemap, etc.). Re-created on every `buildSite` + or `runSite`. + +### 7.4 Git submodules + +`.gitmodules` (repo root): + +- `config` → `https://github.com/SpineEventEngine/config` +- `docs/_examples` → `https://github.com/spine-examples/hello-validation` +- `docs/_time` → `https://github.com/SpineEventEngine/time` + +Notes: + +- `_examples` contains the Hello Validation example projects + (`first-model`, `first-model-with-framework`, `external`). The settings + file there is the canonical list; the `includeBuild` referenced by + `docs/GRADLE.md` lives in `_examples/settings.gradle.kts`, not in + `docs/`. +- `_time` is the Spine Time library, used as the *implementation example* + for custom validation. The `_script/embed-code` runs + `git submodule update --remote --merge --recursive`, so the submodules + track their default remote branches when running the embed pipeline. + +### 7.5 `embed-code-go` pinning + +- The tool is consumed as **checked-in prebuilt binaries** under + `docs/_bin/`: + - `embed-code-linux`, `embed-code-macos`, `embed-code-windows.exe`. +- There is no version pin in source form in this repo. The + `_script/check-samples` selects the Linux binary on GitHub Actions + (`GITHUB_ACTIONS=true`) and the macOS binary locally. The Windows binary + is present but currently not selected by either script. +- `_script/embed-code` hard-codes the `embed-code-macos` binary path. +- "Updating `embed-code-go`" therefore means rebuilding the binaries from + https://github.com/SpineEventEngine/embed-code-go and replacing the + artifacts under `docs/_bin/`. + +### 7.6 `settings/embed-code.yml` + +Current contents declare five `code-path` source roots: + +| Name | Path | What it exposes | +|-----------|---------------------|----------------------------------------------------------------| +| `root` | `../..` | The Validation repo root (top-level files, all modules). | +| `examples`| `../_examples` | The Hello Validation example projects (Git submodule). | +| `runtime` | `../../jvm-runtime` | The `jvm-runtime` module. | +| `java` | `../../java` | The Java code-generation module. | +| `context` | `../../context` | The custom-validation context module. | + +Plus: + +- `docs-path: "../content/docs/"` — root of pages that can host embedded + snippets. +- `code-includes` — file globs the tool considers as embeddable sources: + `.gitignore`, `**/*.kts`, `**/*.md`, `**/*.proto`, `**/*.java`, + `**/*.kt`, `**/*.yml`. + +### 7.7 Documentation versions and sidenav target + +- `docs/data/versions.yml` declares two `validation` entries: + `2-0-0-snapshot` (`is_main: true`) and `2-0-x` (not main, both + `switcher` flags false). +- `docs/data/docs/validation/` contains a `sidenav.yml` only for + `2-0-0-snapshot/`. There is no `2-0-x/` sub-directory. The new sub-tree + must be added to + `docs/data/docs/validation/2-0-0-snapshot/sidenav.yml` only. + +### 7.8 Other observations relevant to the docs + +- `docs/_options/options.proto` is a copy of the Protobuf options surface + used by the documentation embeds. Not strictly part of the new doc's + scope but worth a brief mention in `_index.md` or `embedded-examples.md`. +- The version bump procedure in the draft references "the version in + `version.gradle.kts`" — confirmed at the repo root + (`val validationVersion by extra("2.0.0-SNAPSHOT.419")`). +- The custom Gradle task plumbing (`UpdatePluginVersion`, + `io.spine.gradle.RunGradle`) is shared across the SDK; this repo + consumes them from the local `buildSrc`. + +## 8. Out of scope - Changes to historical doc versions (`2-0-x` and earlier) or their `sidenav.yml` files. From 698c09ca410633a5512f7206520758bfe4f11f3f Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:24:06 +0100 Subject: [PATCH 09/40] Draft the documentation2 structure --- .../developer/documentation/_index.md | 33 +++++++ .../developer/documentation/build-tasks.md | 46 ++++++++++ .../documentation/embedded-examples.md | 42 +++++++++ .../developer/documentation/procedures.md | 91 +++++++++++++++++++ .../developer/documentation/tooling.md | 36 ++++++++ .../validation/2-0-0-snapshot/sidenav.yml | 13 +++ 6 files changed, 261 insertions(+) create mode 100644 docs/content/docs/validation/developer/documentation/_index.md create mode 100644 docs/content/docs/validation/developer/documentation/build-tasks.md create mode 100644 docs/content/docs/validation/developer/documentation/embedded-examples.md create mode 100644 docs/content/docs/validation/developer/documentation/procedures.md create mode 100644 docs/content/docs/validation/developer/documentation/tooling.md diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md new file mode 100644 index 0000000000..e00d4c6180 --- /dev/null +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -0,0 +1,33 @@ +--- +title: Documentation process +description: How the Spine Validation documentation is authored, built, previewed, and released. +headline: Documentation +--- + +# Documentation process + + + +## What lives under `docs/` + + + +## Relationship to the `spine.io` website + + + +## Reading map + + + +- [Build tasks](build-tasks.md) +- [Embedded examples](embedded-examples.md) +- [External tooling](tooling.md) +- [Procedures](procedures.md) diff --git a/docs/content/docs/validation/developer/documentation/build-tasks.md b/docs/content/docs/validation/developer/documentation/build-tasks.md new file mode 100644 index 0000000000..6e03711cfb --- /dev/null +++ b/docs/content/docs/validation/developer/documentation/build-tasks.md @@ -0,0 +1,46 @@ +--- +title: Build tasks +description: The Gradle tasks defined for the documentation module, what they do, and how they are wired. +headline: Documentation +--- + +# Build tasks + + + +## Working directory and paths + + + +## Hugo tasks + + + +## Plugin-version tasks + + + +## Code-embedding tasks + + + +## Aggregate tasks + + + +## Task dependency map + + diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md new file mode 100644 index 0000000000..fc9c0674c6 --- /dev/null +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -0,0 +1,42 @@ +--- +title: Embedded examples +description: How example source code is embedded into the documentation pages. +headline: Documentation +--- + +# Embedded examples + + + +## Example sources + + + +## Spine Time as an implementation example + + + +## The `settings/embed-code.yml` file + + + +## Embedding syntax on the page side + + + +## How embedding runs + + diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md new file mode 100644 index 0000000000..a13c46779a --- /dev/null +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -0,0 +1,91 @@ +--- +title: Procedures +description: Step-by-step recipes for recurring documentation-related tasks. +headline: Documentation +--- + +# Procedures + + + +## Incrementing the version of Validation + + + +## Updating the version of the CoreJvm Compiler + + + +## Refreshing embedded example sources from Spine Time + + + +## Adding a new embedded code example + + + +## Adding or updating a documentation page + + + +## Updating `site-commons` + + + +## Updating `embed-code-go` + + + +## Building the documentation locally + + + +## Previewing the documentation locally + + diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md new file mode 100644 index 0000000000..7dd4e5f3c0 --- /dev/null +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -0,0 +1,36 @@ +--- +title: External tooling +description: The external tools the documentation build depends on and how they are consumed. +headline: Documentation +--- + +# External tooling + + + +## `site-commons` + + + +## `embed-code-go` + + + +## Hugo and the Node toolchain + + diff --git a/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml b/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml index 464e618c4d..3430f06d37 100644 --- a/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml +++ b/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml @@ -102,3 +102,16 @@ file_path: developer/testing-strategy - page: Build, packaging, and release file_path: developer/build-and-release + - page: Documentation process + key: documentation + children: + - page: Overview + file_path: developer/documentation + - page: Build tasks + file_path: developer/documentation/build-tasks + - page: Embedded examples + file_path: developer/documentation/embedded-examples + - page: External tooling + file_path: developer/documentation/tooling + - page: Procedures + file_path: developer/documentation/procedures From 5205ba6b31806e72a409413a03a489a38f17ee33 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:42:50 +0100 Subject: [PATCH 10/40] Add docs2 content --- .../developer/documentation/_index.md | 77 ++++++-- .../developer/documentation/build-tasks.md | 175 ++++++++++++++++-- 2 files changed, 216 insertions(+), 36 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md index e00d4c6180..5fff261f21 100644 --- a/docs/content/docs/validation/developer/documentation/_index.md +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -6,28 +6,73 @@ headline: Documentation # Documentation process - +This section describes the technical side of the Spine Validation +documentation: how the `docs/` module is organized, which Gradle tasks drive +the build, how source code is embedded into pages, which external tools the +build depends on, and the recurring procedures contributors need to perform. + +The `docs/` module is a *staging area*, not a published site. The pages and +data under it are merged into the main documentation project +([SpineEventEngine/documentation][main-documentation]) and published from +there to the [`spine.io`][spine-io] website. The build wiring on this page +exists to let contributors preview, validate, and iterate on the content of +this repository before that merge happens. ## What lives under `docs/` - +The module is laid out as a Hugo project supplemented by Gradle wiring and a +Go-based code-embedding tool. The top-level layout is: + +| Path | Role | +|------------------|----------------------------------------------------------------------------| +| `content/` | Markdown pages of the documentation, organized by section and version. | +| `data/` | Site data files, including the per-version `sidenav.yml` navigation. | +| `layouts/` | Hugo layout overrides specific to the Validation site. | +| `build.gradle.kts` | Gradle build script for the `:docs` subproject. See "[Build tasks](build-tasks.md)". | +| `_preview/` | Hugo project root used to render and serve the site locally. | +| `_examples/` | Git submodule with the Hello Validation example projects. | +| `_time/` | Git submodule with the Spine Time library, used as the implementation example for custom validation. | +| `_settings/` | Configuration for the code-embedding tool — see "[Embedded examples](embedded-examples.md)". | +| `_script/` | Shell scripts that the Gradle tasks shell out to. | +| `_bin/` | Prebuilt `embed-code-go` binaries for Linux, macOS, and Windows. | +| `_options/` | A copy of the Validation Protobuf options surface kept alongside the docs. | + +The underscore prefix marks directories that are *not* part of the Hugo site +tree — Hugo ignores top-level paths starting with `_`. Everything Hugo +actually renders lives under `content/`, `data/`, and `layouts/`. ## Relationship to the `spine.io` website - +There is no automated deployment from this repository. The CI workflows +under `.github/workflows/` only build the example sources +(`:docs:buildAll`) and verify that the embedded snippets are in sync with +their sources (`:docs:checkSamples`). Publication happens through the main +documentation project, which pulls the Markdown content of `docs/content/` +together with content from other Spine projects and renders the unified +[spine.io](https://spine.io) site. + +This split has two practical consequences for contributors: + +- The Hugo site rendered under `_preview/public/` is for local inspection + only; treat it as a staging artifact, not as the published site. +- Anything that the main documentation project does not pick up — for + example, files outside `content/` and `data/` — is *not* shipped, no + matter how it renders locally. -## Reading map +## How to read the rest of this section - +- "[Build tasks](build-tasks.md)" — every Gradle task defined in + `docs/build.gradle.kts`, what each does, and how they depend on each + other. +- "[Embedded examples](embedded-examples.md)" — how source code from the + Validation modules and the `_examples`/`_time` submodules ends up inside + the documentation pages. +- "[External tooling](tooling.md)" — the `site-commons` Hugo theme and the + `embed-code-go` tool, including how each is wired into the build. +- "[Procedures](procedures.md)" — step-by-step recipes for the recurring + documentation tasks (version bumps, submodule refresh, adding pages and + embedded examples, updating external tooling, building and previewing + locally). -- [Build tasks](build-tasks.md) -- [Embedded examples](embedded-examples.md) -- [External tooling](tooling.md) -- [Procedures](procedures.md) +[main-documentation]: https://github.com/SpineEventEngine/documentation +[spine-io]: https://spine.io/ diff --git a/docs/content/docs/validation/developer/documentation/build-tasks.md b/docs/content/docs/validation/developer/documentation/build-tasks.md index 6e03711cfb..9f433ee4ce 100644 --- a/docs/content/docs/validation/developer/documentation/build-tasks.md +++ b/docs/content/docs/validation/developer/documentation/build-tasks.md @@ -6,41 +6,176 @@ headline: Documentation # Build tasks - +The `:docs` subproject is configured in [`docs/build.gradle.kts`][docs-build]. +The tasks declared there are thin Gradle wrappers around shell scripts in +`docs/_script/` and the `embed-code-go` binaries in `docs/_bin/`. This page +documents every task, what it does, where it lands its output, and how the +tasks depend on each other. ## Working directory and paths - +All shell scripts under `docs/_script/` assume that `docs/` is the current +working directory. The Gradle tasks take care of this automatically — the +`Exec` tasks invoke each script with an absolute path under `$projectDir`, so +running them as `./gradlew :docs:` from the repository root works. + +When invoking the scripts directly (for example, during debugging), `cd` into +`docs/` first: + +```bash +cd docs +./_script/hugo-serve +``` + +The scripts navigate further on their own — for example, `_script/hugo-serve` +enters `_preview/` before launching `hugo server`, and `_script/embed-code` +enters `_bin/` before invoking the embedding tool. ## Hugo tasks - +These tasks drive Hugo via the scripts in `docs/_script/`. + +### `installDependencies` + +Runs `_script/install-dependencies`, which executes `npm install` inside +`_preview/`. The script installs the Node devDependencies declared in +`_preview/package.json` (`postcss`, `autoprefixer`, +`@fullhuman/postcss-purgecss`, and so on). All Hugo-related tasks depend on +this task, so it is rarely invoked manually. + +### `runSite` + +Runs `_script/hugo-serve` → `hugo server` from `_preview/`. The Hugo dev +server hot-reloads pages on edits to `docs/content/`. This is the standard +way to preview documentation changes locally; see the "Previewing the +documentation locally" recipe in "[Procedures](procedures.md)". + +### `buildSite` + +Runs `_script/hugo-build` → `hugo` from `_preview/`. The Hugo build emits the +static site under `docs/_preview/public/`. The output is intended for local +inspection only — it is *not* the artifact published to `spine.io`. See the +"Building the documentation locally" recipe in +"[Procedures](procedures.md)". ## Plugin-version tasks - +These tasks keep the plugin coordinates in the example projects under +`docs/_examples/` aligned with the versions used elsewhere in the +repository. + +The task type is [`UpdatePluginVersion`][update-plugin-version], defined in +`buildSrc/`. It scans recursively for `build.gradle.kts` files under the +configured directory and rewrites declarations of the form +`id("") version ""`. When `kotlinVersion` is also set, +it additionally rewrites `kotlin("") version ""` lines. + +### `updateValidationPluginVersion` + +Updates `id("io.spine.validation") version "…"` in every `build.gradle.kts` +under `docs/_examples/` to `validationVersion` from +[`version.gradle.kts`][version-gradle], and updates `kotlin("…") version "…"` +to `Kotlin.version`. + +### `updateCoreJvmPluginVersion` + +Updates `id("io.spine.core-jvm") version "…"` to `CoreJvmCompiler.version` +from the [`CoreJvmCompiler`][core-jvm-compiler-dep] dependency object in +`buildSrc/`. + +### `updatePluginVersions` + +Aggregator that depends on both tasks above. This is the task contributors +run after bumping the Validation version or the CoreJvm Compiler version; +see the recipes in "[Procedures](procedures.md)". ## Code-embedding tasks - +These tasks invoke the `embed-code-go` binaries under `docs/_bin/`. Both +depend on `updatePluginVersions`, so the example sources always reflect the +current plugin versions before snippets are embedded or checked. + +### `embedCode` + +Runs `_script/embed-code`. The script first runs + +```bash +git submodule update --remote --merge --recursive +``` + +so that `_examples/` and `_time/` track their default remote branches. It +then invokes `embed-code-macos` with `-mode="embed"` and the configuration at +`_settings/embed-code.yml`, which rewrites the fenced regions in the Markdown +pages under `content/` from their source snippets. Run this task manually +after editing an embedded snippet or after pointing a source root at a new +commit. See "[Embedded examples](embedded-examples.md)" for the +configuration format and "[Procedures](procedures.md)" for the day-to-day +recipe. + +### `checkSamples` + +Runs `_script/check-samples`. The script selects `embed-code-linux` when the +`GITHUB_ACTIONS` environment variable is `true`, and `embed-code-macos` +otherwise, then invokes it with `-mode="check"`. The tool exits non-zero if +any embedded snippet drifts from its source. This task is executed by the +[Code Embedding][check-code-embedding] GitHub workflow on every pull +request. ## Aggregate tasks - +These tasks tie the example projects under `docs/_examples/` into the main +build so that the embedded code is actually compilable. + +### `publishAllToMavenLocal` + +Aggregator that depends on every `PublishToMavenLocal` task across the root +project's subprojects. Running it stages the current Validation artifacts to +the local Maven repository, where the example projects can resolve them +through `mavenLocal()`. + +### `buildExamples` + +Custom `RunGradle` task that delegates to the `buildAll` task inside +`docs/_examples/`. It depends on `publishAllToMavenLocal` (so the examples +build against the just-published artifacts) and on `updatePluginVersions` +(so the example build files reference the current plugin versions). + +### `buildAll` + +The conventional "build everything for the documentation" entry point. +Depends on `publishAllToMavenLocal` and `buildExamples`. This is the task +invoked by the [Code Embedding][check-code-embedding] GitHub workflow to +validate that every embedded snippet still compiles inside a real Gradle +build. ## Task dependency map - +| Task | Depends on | +|---------------------------------|-------------------------------------------------------------| +| `installDependencies` | — | +| `runSite` | `installDependencies` | +| `buildSite` | `installDependencies` | +| `updateValidationPluginVersion` | — | +| `updateCoreJvmPluginVersion` | — | +| `updatePluginVersions` | `updateValidationPluginVersion`, `updateCoreJvmPluginVersion` | +| `embedCode` | `updatePluginVersions` | +| `checkSamples` | `updatePluginVersions` | +| `publishAllToMavenLocal` | all `PublishToMavenLocal` tasks across the root project | +| `buildExamples` | `publishAllToMavenLocal`, `updatePluginVersions` | +| `buildAll` | `publishAllToMavenLocal`, `buildExamples` | + +## What's next + +- "[Embedded examples](embedded-examples.md)" — how `embedCode` and + `checkSamples` decide what source goes into which page. +- "[External tooling](tooling.md)" — the `site-commons` Hugo theme that the + Hugo tasks render against, and how the `embed-code-go` binaries get into + `_bin/`. +- "[Procedures](procedures.md)" — the recipes that combine these tasks into + end-to-end contributor workflows. + +[docs-build]: https://github.com/SpineEventEngine/validation/blob/master/docs/build.gradle.kts +[update-plugin-version]: https://github.com/SpineEventEngine/validation/blob/master/buildSrc/src/main/kotlin/io/spine/gradle/docs/UpdatePluginVersion.kt +[version-gradle]: https://github.com/SpineEventEngine/validation/blob/master/version.gradle.kts +[core-jvm-compiler-dep]: https://github.com/SpineEventEngine/validation/blob/master/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt +[check-code-embedding]: https://github.com/SpineEventEngine/validation/blob/master/.github/workflows/check-code-embedding.yml From 76912959d39ceb94c473a7d839ca241178b738e7 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:44:54 +0100 Subject: [PATCH 11/40] Add docs2 content --- .../developer/documentation/_index.md | 2 +- .../documentation/embedded-examples.md | 182 ++++++++++++++++-- 2 files changed, 162 insertions(+), 22 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md index 5fff261f21..ba36460804 100644 --- a/docs/content/docs/validation/developer/documentation/_index.md +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -14,7 +14,7 @@ build depends on, and the recurring procedures contributors need to perform. The `docs/` module is a *staging area*, not a published site. The pages and data under it are merged into the main documentation project ([SpineEventEngine/documentation][main-documentation]) and published from -there to the [`spine.io`][spine-io] website. The build wiring on this page +there to the [spine.io][spine-io] website. The build wiring on this page exists to let contributors preview, validate, and iterate on the content of this repository before that merge happens. diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index fc9c0674c6..77ffb139ce 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -6,37 +6,177 @@ headline: Documentation # Embedded examples - +The documentation embeds snippets from real source files instead of inlining +them as plain Markdown. This keeps the snippets in lock-step with the code +they document: when a method signature, a Protobuf option, or an example +project file changes, the documentation either updates automatically (when +`:docs:embedCode` runs) or fails CI (when `:docs:checkSamples` runs against +a stale page). The two source pools the documentation pulls from are the +Validation modules under the repository root and two Git submodules under +`docs/`. ## Example sources - +The `docs/_examples/` directory is a Git submodule pointing to the +[`spine-examples/hello-validation`][hello-validation] repository. It hosts +the small, runnable example projects that the User's Guide walks through: -## Spine Time as an implementation example +| Project | Purpose | +|-------------------------------|------------------------------------------------------------------------------------------| +| `first-model` | The minimal Protobuf model with field-level constraints used in "[Getting started](../../user/01-getting-started/)". | +| `first-model-with-framework` | The same model extended with `MessageValidator` and registry wiring. | +| `external` | A consumer project that depends on validated messages from another module. | - +These projects compile and run against the just-built Validation artifacts. +The `:docs:buildExamples` task delegates a `buildAll` invocation into +`docs/_examples/`, and `:docs:publishAllToMavenLocal` stages the Validation +artifacts the example projects resolve through `mavenLocal()`. See +"[Build tasks](build-tasks.md)" for the wiring. -## The `settings/embed-code.yml` file +## Spine Time as the implementation example - +The custom-validation chapter needs a real, non-trivial implementation of +the extension points described in "[Extension points](../extension-points.md)" +and "[Adding a new built-in validation option](../adding-a-built-in-option.md)". +[Spine Time][spine-time] is that example: it defines its own validation +options (`(when)`, `(time)`) and implements them through the same +extension points the documentation describes. + +To embed snippets from Spine Time's actual source — not a copy that would +inevitably drift — the library is included as the `docs/_time/` Git +submodule pointing at [`SpineEventEngine/time`][spine-time]. The +code-embedding tool then reads snippets straight from the submodule +working tree. + +## The `_settings/embed-code.yml` file + +The configuration file [`docs/_settings/embed-code.yml`][embed-code-yml] +declares the source roots the embedding tool understands, where the +documentation pages live, and which files are considered embeddable. + +```yaml +code-path: + - name: "root" + path: "../.." + - name: "examples" + path: "../_examples" + - name: "runtime" + path: "../../jvm-runtime" + - name: "java" + path: "../../java" + - name: "context" + path: "../../context" +docs-path: "../content/docs/" +code-includes: + - ".gitignore" + - "**/*.kts" + - "**/*.md" + - "**/*.proto" + - "**/*.java" + - "**/*.kt" + - "**/*.yml" +``` + +### Source roots (`code-path`) + +Each entry maps a logical *name* to a directory *path*, resolved relative +to `docs/_bin/` (because the scripts `cd _bin` before invoking the +binary). A page references a source root by its name, prefixed with `$`. + +| Name | Path | What it exposes | +|------------|---------------------|--------------------------------------------------------------------------| +| `root` | `../..` | The Validation repository root — top-level files (`version.gradle.kts`, `build.gradle.kts`, …) and any module not separately mapped. | +| `examples` | `../_examples` | The Hello Validation example projects (the submodule above). | +| `runtime` | `../../jvm-runtime` | The `:jvm-runtime` module — runtime library sources used in "[Runtime library](../runtime-library.md)". | +| `java` | `../../java` | The `:java` module — Java code-generation sources used in "[Java code generation](../java-code-generation.md)". | +| `context` | `../../context` | The `:context` module — the custom-validation context sources. | + +To embed from Spine Time, use the `$root` source root with a +`docs/_time/...` path. There is no dedicated source root for `_time/` +because everything in that submodule is reachable through the repository +root. + +### Pages directory (`docs-path`) + +`docs-path: "../content/docs/"` points the tool at the Markdown tree it +should scan when running `embedCode` or `checkSamples`. Only files under +this directory are considered for embedding. + +### Embeddable file types (`code-includes`) + +The globs under `code-includes` filter which source files the tool will +read when resolving an `` block. Adding a new file extension +(for example, `**/*.json` for embedded JSON snippets) means appending it +to this list. ## Embedding syntax on the page side - +An `` element marks a region in a Markdown page that the tool +manages. The tool replaces the *fenced code block* immediately following +the element with the content extracted from the referenced source file +between the `start` and `end` patterns. + +```markdown + + +` ` `kotlin +val validationVersion by extra("2.0.0-SNAPSHOT.419") +` ` ` +``` + +(The fence is shown with spaces to keep this page renderable.) The four +relevant attributes are: + +- `file` — `$source-root/relative/path/to/file.ext` where `source-root` + is a name from `code-path`. +- `start` — a regular expression matched against a single line. The + matching line is the *first* line included. +- `end` — a regular expression matched against a single line. The + matching line is the *last* line included. To include a single line, + use the same pattern for both. +- The language tag on the fenced block (`kotlin`, `java`, `proto`, …) + controls syntax highlighting; the tool does not derive it from the + source extension. + +Other working examples in the repository to copy from: + +- A Java method body — see [`runtime-library.md`][runtime-library] for + patterns like `start="public static M check"` with + `end="^ \}"`. +- A Kotlin class declaration — same page, the `DetectedViolation` snippet. +- A Gradle DSL block — see [`build-and-release.md`][build-and-release] + for the `spinePublishing { … }` example, anchored with `end="^}"`. ## How embedding runs - +The two Gradle tasks that drive the embedding flow are documented on +"[Build tasks](build-tasks.md)": + +- `:docs:embedCode` rewrites the fenced regions in place. Use it after + editing a `start`/`end` pattern, adding a new `` element, + or pointing a source root at a new commit. +- `:docs:checkSamples` verifies that every fenced region matches what + the tool would produce now, without writing. The + [Code Embedding][check-code-embedding] workflow runs this on every + pull request. + +Both tasks shell out to the `embed-code-go` binaries checked in under +`docs/_bin/`. See "[External tooling](tooling.md)" for how those +binaries are kept up to date. + +## What's next + +- "[External tooling](tooling.md)" — the `site-commons` Hugo theme and + the `embed-code-go` tool, including how each is updated. +- "[Procedures](procedures.md)" — the day-to-day recipes for adding a + new embedded example and for refreshing the Spine Time submodule. + +[hello-validation]: https://github.com/spine-examples/hello-validation +[spine-time]: https://github.com/SpineEventEngine/time +[embed-code-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/_settings/embed-code.yml +[runtime-library]: https://github.com/SpineEventEngine/validation/blob/master/docs/content/docs/validation/developer/runtime-library.md +[build-and-release]: https://github.com/SpineEventEngine/validation/blob/master/docs/content/docs/validation/developer/build-and-release.md +[check-code-embedding]: https://github.com/SpineEventEngine/validation/blob/master/.github/workflows/check-code-embedding.yml From 9573de5d7f4c870067a4c8e1ad2dfa9749cf2504 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:45:18 +0100 Subject: [PATCH 12/40] Avoid redundant backticks --- docs/content/docs/validation/developer/documentation/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md index ba36460804..e0182d7416 100644 --- a/docs/content/docs/validation/developer/documentation/_index.md +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -41,7 +41,7 @@ The underscore prefix marks directories that are *not* part of the Hugo site tree — Hugo ignores top-level paths starting with `_`. Everything Hugo actually renders lives under `content/`, `data/`, and `layouts/`. -## Relationship to the `spine.io` website +## Relationship to the spine.io website There is no automated deployment from this repository. The CI workflows under `.github/workflows/` only build the example sources From e07de765e78bffbd18a23013412c84531e9ab3b6 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:50:08 +0100 Subject: [PATCH 13/40] Avoid redundant backticks --- .../docs/validation/developer/documentation/build-tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/validation/developer/documentation/build-tasks.md b/docs/content/docs/validation/developer/documentation/build-tasks.md index 9f433ee4ce..85cb9a4d76 100644 --- a/docs/content/docs/validation/developer/documentation/build-tasks.md +++ b/docs/content/docs/validation/developer/documentation/build-tasks.md @@ -54,7 +54,7 @@ documentation locally" recipe in "[Procedures](procedures.md)". Runs `_script/hugo-build` → `hugo` from `_preview/`. The Hugo build emits the static site under `docs/_preview/public/`. The output is intended for local -inspection only — it is *not* the artifact published to `spine.io`. See the +inspection only — it is *not* the artifact published to spine.io. See the "Building the documentation locally" recipe in "[Procedures](procedures.md)". From ab0336e38be8fb253e44df94844a5fb3b1ee8651 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:52:24 +0100 Subject: [PATCH 14/40] Describe documentation tooling --- .../developer/documentation/tooling.md | 138 +++++++++++++++--- 1 file changed, 119 insertions(+), 19 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md index 7dd4e5f3c0..83dbb726a2 100644 --- a/docs/content/docs/validation/developer/documentation/tooling.md +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -6,31 +6,131 @@ headline: Documentation # External tooling - +The documentation build leans on three external pieces of tooling: the +[site-commons][site-commons] Hugo theme, the [embed-code-go][embed-code-go] +tool, and the Hugo + Node toolchain that drives the static-site build. This +page documents what each is, how it is wired into the build, and where it is +pinned. The step-by-step recipes for updating each live in +"[Procedures](procedures.md)". ## `site-commons` - +[site-commons][site-commons] is the shared Hugo theme and layout library +used by the documentation sites of Spine projects. It provides the +navigation chrome, the sidenav rendering that consumes the +[`sidenav.yml`](../../../../data/docs/validation/2-0-0-snapshot/sidenav.yml) +files, code-highlighting partials, and other Hugo components that are +common across Spine sites. + +It is consumed as a Hugo module. Two files wire it in: + +- `docs/_preview/hugo.toml` imports `site-commons` and the local `../..` + module (the `docs/` directory itself) under `[module] [[module.imports]]`: + + ```toml + [module] + [[module.imports]] + path = '../..' + [[module.imports]] + path = 'github.com/SpineEventEngine/site-commons' + ``` + + Hugo modules sit on top of a Go module, so this import is resolved through + `_preview/go.mod`. + +- `docs/_preview/go.mod` pins the exact `site-commons` version, expressed as + a pseudo-version timestamp: + + ```text + require ( + github.com/SpineEventEngine/site-commons v0.0.0-20260507130158-84db050dfe11 // indirect + github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20800 // indirect + ) + ``` + +The `hugo-mod-bootstrap-scss` dependency is a transitive Hugo module pulled +in by `site-commons`; it is listed here because Hugo resolves the full +module graph through this `go.mod`. + +The repository-root `docs/go.mod` is a separate file for tooling that +inspects the `docs/` directory as a Go module on its own. The +*authoritative* pin for what gets rendered locally is the one in +`_preview/go.mod`. + +### Updating `site-commons` + +The procedure is the one documented under "[Theme updates][theme-updates]" +in the `site-commons` README. From `docs/_preview/`, run: + +```bash +hugo mod get -u github.com/SpineEventEngine/site-commons +``` + +Then commit and push the resulting changes to `go.mod` and `go.sum`. The +companion "Updating `site-commons`" recipe in +"[Procedures](procedures.md)" wraps this command with the surrounding +verification steps (preview, sanity check). ## `embed-code-go` - +[embed-code-go][embed-code-go] is the command-line tool that powers +`:docs:embedCode` and `:docs:checkSamples`. It reads the +`` elements described in "[Embedded examples](embedded-examples.md)", +resolves each `file` reference against the source roots in +[`_settings/embed-code.yml`](../../../../_settings/embed-code.yml), and +either rewrites the fenced code block beneath the element (`-mode="embed"`) +or fails non-zero on drift (`-mode="check"`). + +The tool is consumed as **prebuilt binaries checked into the repository**, +not as a Go module or downloaded artifact. The binaries live under +`docs/_bin/`: + +| File | When it is used | +|----------------------------|--------------------------------------------------------------| +| `embed-code-linux` | `_script/check-samples` when `GITHUB_ACTIONS=true` (CI). | +| `embed-code-macos` | `_script/check-samples` locally; `_script/embed-code` always. | +| `embed-code-windows.exe` | Currently not selected by either script. | + +There is no version string recorded in this repository. Updating to a new +release of `embed-code-go` means rebuilding the binaries from its source +repository for each target platform and replacing the artifacts under +`docs/_bin/`. The step-by-step recipe is "Updating `embed-code-go`" in +"[Procedures](procedures.md)". ## Hugo and the Node toolchain - +The `:docs:installDependencies` task runs `npm install` inside `_preview/` +to install the Node packages that Hugo's asset pipeline consumes. The +relevant declarations are in `docs/_preview/package.json`: + +```json +"devDependencies": { + "@fullhuman/postcss-purgecss": "^7.0.2", + "autoprefixer": "^10.4.22", + "postcss": "^8.5.10", + "postcss-cli": "^11.0.1", + "postcss-discard-comments": "^7.0.5" +} +``` + +These power the PostCSS processing chain that Hugo invokes for CSS assets +(autoprefixing, purging unused rules from the Bootstrap-based theme). +`package-lock.json` is committed and is the authoritative pin. + +Hugo itself is *not* installed by the build — the `_script/hugo-serve` and +`_script/hugo-build` scripts assume that `hugo` is on the `PATH`. Install it +from the [Hugo project][hugo-install] before running `:docs:runSite` or +`:docs:buildSite` for the first time. The version is not pinned in this +repository; use a recent extended release that matches what `site-commons` +expects. + +## What's next + +- "[Procedures](procedures.md)" — the recipes for updating `site-commons` + and `embed-code-go`, and for installing or upgrading the local Hugo and + Node toolchain. + +[site-commons]: https://github.com/SpineEventEngine/site-commons +[theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates +[embed-code-go]: https://github.com/SpineEventEngine/embed-code-go +[hugo-install]: https://gohugo.io/installation/ From 54446fd79870dfa255361f5237b3b31e664993f5 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 18:53:46 +0100 Subject: [PATCH 15/40] Add Claude memory --- .../memory/MEMORY.md | 1 + .../memory/feedback_spine_io_no_backticks.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md create mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md new file mode 100644 index 0000000000..6a454d5eba --- /dev/null +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md @@ -0,0 +1 @@ +- [Do not use backticks around "spine.io"](feedback_spine_io_no_backticks.md) — render spine.io as plain prose or a link, never as code. diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md new file mode 100644 index 0000000000..73df127e59 --- /dev/null +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md @@ -0,0 +1,19 @@ +--- +name: Do not use backticks around "spine.io" +description: When writing docs in this repo, write spine.io as plain prose (or as a link), never wrapped in backticks. +type: feedback +--- + +Do not put backticks around `spine.io` — write it as plain prose or, where +appropriate, as a Markdown link to https://spine.io. The user removed +backticks I had added in `_index.md` and `build-tasks.md` and explicitly +asked me not to use them. + +**Why:** "spine.io" is a brand/site name in this project, not code or a +file/directory identifier. The repo's documentation-guidelines say to format +file and directory names as code; brand names are not in that bucket. + +**How to apply:** In all docs and prose under this repo, render "spine.io" +as `spine.io` (no backticks) or as `[spine.io](https://spine.io)`. The same +default likely applies to other brand/site names — keep them plain unless +they unambiguously refer to a file or identifier. From f48ea901666da41d66c353bb6c16ac65b19fa3d5 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:00:21 +0100 Subject: [PATCH 16/40] Describe the documentation procedures --- .../developer/documentation/procedures.md | 322 +++++++++++++++--- 1 file changed, 266 insertions(+), 56 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index a13c46779a..90f0b42d0f 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -6,86 +6,296 @@ headline: Documentation # Procedures - +Each section below is an executable recipe. Unless stated otherwise, run +commands from the repository root and prefix Gradle tasks with `./gradlew`. +The conceptual background for each procedure lives on the sibling pages: +"[Build tasks](build-tasks.md)", "[Embedded examples](embedded-examples.md)", +and "[External tooling](tooling.md)". ## Incrementing the version of Validation - +1. Update the version literal in [`version.gradle.kts`][version-gradle]: + + ```kotlin + val validationVersion by extra("") + ``` + +2. Propagate the new version into the example projects' plugin coordinates: + + ```bash + ./gradlew :docs:updatePluginVersions + ``` + + This rewrites the `io.spine.validation` plugin version (and the + `io.spine.core-jvm` plugin version) in every `build.gradle.kts` under + `docs/_examples/`. + +3. Commit `version.gradle.kts` on its own with: + + ```text + Bump version -> `` + ``` + +4. Commit the remaining files touched by step 2 with: + + ```text + Bump Validation -> `` + ``` + +5. Run a clean build and refresh the dependency reports: + + ```bash + ./gradlew clean build + ``` + + Then commit the regenerated `pom.xml` and `dependencies.md` with: + + ```text + Update dependency reports + ``` + + This step follows the same convention used elsewhere in the Spine SDK + projects. ## Updating the version of the CoreJvm Compiler - +1. Update the version in the `CoreJvmCompiler` dependency object under + [`buildSrc`][core-jvm-compiler-dep]. + +2. Propagate the new version into the example projects' plugin coordinates: + + ```bash + ./gradlew :docs:updatePluginVersions + ``` + + This rewrites the `io.spine.core-jvm` plugin version (and the + `io.spine.validation` plugin version) in every `build.gradle.kts` under + `docs/_examples/`. ## Refreshing embedded example sources from Spine Time - +The Spine Time library at `docs/_time/` is a Git submodule. Use these +steps when first cloning the repository or when intentionally moving the +submodule to a different commit. + +1. Initialize and fetch the submodule on a fresh clone: + + ```bash + git submodule update --init --recursive docs/_time + ``` + +2. To move `_time/` to a specific commit, fetch and check it out inside + the submodule: + + ```bash + cd docs/_time + git fetch origin + git checkout + cd - + ``` + +3. Re-embed snippets that pull from the submodule and verify: + + ```bash + ./gradlew :docs:embedCode + ./gradlew :docs:checkSamples + ``` + +4. Commit the updated submodule pointer: + + ```bash + git add docs/_time + git commit -m "Update Spine Time submodule -> " + ``` + +Note that `:docs:embedCode` itself runs +`git submodule update --remote --merge --recursive` as part of its +script. The manual checkout in step 2 is what *pins* the submodule to a +specific revision; the automatic update tracks the submodule's default +remote branch. ## Adding a new embedded code example - +1. If the source file lives outside the existing source roots in + [`_settings/embed-code.yml`][embed-code-yml], add a new entry under + `code-path` (a `name` plus a path relative to `docs/_bin/`). If the + file extension is not yet listed, add a glob under `code-includes`. + +2. In the target Markdown page, write an `` element followed + by an empty fenced code block. For example: + + ```markdown + + + ``` + + The `start` and `end` attributes are regular expressions matched + against single lines; the matching lines are included. + +3. Embed and verify: + + ```bash + ./gradlew :docs:embedCode + ./gradlew :docs:checkSamples + ``` + + The fenced block under the element is now populated with the snippet. + +4. Preview the page locally (see "Previewing the documentation locally" + below) and confirm the snippet renders with the right syntax + highlighting. + +5. Commit the page, the snippet contents, and any changes to + `_settings/embed-code.yml`. + +For the underlying mechanics, see "[Embedded examples](embedded-examples.md)". ## Adding or updating a documentation page - +1. Create or edit the Markdown file under + `docs/content/docs/validation/
/`. Match the frontmatter + convention used by the surrounding pages (`title`, `description`, + `headline: Documentation`). + +2. Keep the navigation in sync. Update + `docs/data/docs/validation/2-0-0-snapshot/sidenav.yml`: + + - For a new page, add a `page`/`file_path` entry under the + appropriate parent. The `file_path` is relative to + `docs/content/docs/validation/` and omits the `.md` extension; an + `_index.md` maps to its directory path (for example, + `developer/documentation`). + - For a renamed or moved page, update the existing `file_path`. + - For a deleted page, remove the entry. + + Do not edit `sidenav.yml` files under other version directories + unless you are intentionally amending a historical version. + +3. Preview locally (see "Previewing the documentation locally") and + click through every internal link. + +4. Follow the project documentation guidelines in + [`documentation-guidelines.md`][doc-guidelines] — formatting of file + and directory names as code, reference-style external links, no + widows/runts/orphans/rivers. ## Updating `site-commons` - +This is the procedure documented under "[Theme updates][theme-updates]" +in the `site-commons` README, wrapped with the verification steps used +in this repository. + +1. From `docs/_preview/`, pull the latest theme version: + + ```bash + cd docs/_preview + hugo mod get -u github.com/SpineEventEngine/site-commons + cd - + ``` + +2. Preview the site and click through the navigation, code blocks, and + embedded snippets: + + ```bash + ./gradlew :docs:runSite + ``` + +3. Commit and push the resulting changes to + `docs/_preview/go.mod` and `docs/_preview/go.sum`: + + ```bash + git add docs/_preview/go.mod docs/_preview/go.sum + git commit -m "Update site-commons" + ``` ## Updating `embed-code-go` - +The tool is consumed as prebuilt binaries under `docs/_bin/`. Updating +means rebuilding the binaries from the [embed-code-go][embed-code-go] +source repository and replacing the artifacts. + +1. Clone [embed-code-go][embed-code-go] (or update an existing clone) and + check out the release or commit to ship. + +2. Build the three binaries that this repository ships. From the + `embed-code-go` clone, with the Go toolchain on the `PATH`: + + ```bash + GOOS=linux GOARCH=amd64 go build -o embed-code-linux ./cmd/... + GOOS=darwin GOARCH=amd64 go build -o embed-code-macos ./cmd/... + GOOS=windows GOARCH=amd64 go build -o embed-code-windows.exe ./cmd/... + ``` + + Replace the build target paths with whatever the upstream `README` + prescribes if it differs from `./cmd/...`. + +3. Copy the produced binaries into `docs/_bin/`, replacing the existing + files of the same names. + +4. Make sure the macOS and Linux binaries are executable + (`chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux`). + +5. Verify that the new binaries still produce the same embedded output + the repository expects: + + ```bash + ./gradlew :docs:checkSamples + ``` + + If `checkSamples` reports drift caused by the tool itself (formatting, + whitespace, …), run `./gradlew :docs:embedCode` and inspect the diff + before committing. + +6. Commit the updated binaries under `docs/_bin/` with a message that + names the upstream version or commit. ## Building the documentation locally - +1. Build the site: + + ```bash + ./gradlew :docs:buildSite + ``` + +2. The generated static site appears under `docs/_preview/public/`. Open + `docs/_preview/public/index.html` in a browser to inspect the output, + or serve the directory through any static file server. + +3. Treat this output as a *staging artifact only*. Publication to + spine.io happens through the main documentation project, not from + this repository — see "[Documentation process](_index.md)" for the + relationship. ## Previewing the documentation locally - +1. Start the Hugo dev server: + + ```bash + ./gradlew :docs:runSite + ``` + +2. Open the URL printed by `hugo server`, typically + `http://localhost:1313/`. + +3. Edits to Markdown files under `docs/content/` hot-reload + automatically. Edits to `docs/data/` files (including `sidenav.yml`) + and to Hugo layouts require a restart of the task. + +4. To stop the server, press `Ctrl+C` in the terminal running the task. + +## What's next + +- "[Documentation process](_index.md)" — overview and how this section + fits into the wider documentation pipeline. +- "[Build tasks](build-tasks.md)" — reference for every Gradle task + these recipes invoke. + +[version-gradle]: https://github.com/SpineEventEngine/validation/blob/master/version.gradle.kts +[core-jvm-compiler-dep]: https://github.com/SpineEventEngine/validation/blob/master/buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt +[embed-code-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/_settings/embed-code.yml +[doc-guidelines]: https://github.com/SpineEventEngine/validation/blob/master/.agents/documentation-guidelines.md +[theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates +[embed-code-go]: https://github.com/SpineEventEngine/embed-code-go From 2f2ead57d38bcb2ac01bd96603e4e0f758e81890 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:02:23 +0100 Subject: [PATCH 17/40] Replace `GRADLE.md` with `README.md` --- docs/GRADLE.md | 62 -------------------------------------------------- docs/README.md | 22 ++++++++++++++++++ 2 files changed, 22 insertions(+), 62 deletions(-) delete mode 100644 docs/GRADLE.md create mode 100644 docs/README.md diff --git a/docs/GRADLE.md b/docs/GRADLE.md deleted file mode 100644 index dad2871c00..0000000000 --- a/docs/GRADLE.md +++ /dev/null @@ -1,62 +0,0 @@ -# Gradle project of the Validation Documentation - -This document describes the Gradle project structure and build configuration for -building the documentation [preview site](./_preview) for the Spine Validation library. - -The site built by this project is used for development and preview purposes. -It is not meant to be published as-is, but rather to be used as a staging area for -the documentation before it is merged into the main [documentation][main-documentation] project. - -## Build tasks - -The [Gradle build](build.gradle.kts) under the `docs/` provides the following tasks: - -1. **`buildAll`** — building the code of the examples embedded in the documentation. - This ensures that all code snippets are valid and can be compiled. - -2. **`embedCode`** — embedding the source code of the examples into the Markdown files. - This allows the documentation to include up-to-date code snippets from the source files. - This task is meant to be run manually when you write or update the documentation. - -3. **`checkSamples`** — checking that the embedded code snippets in the Markdown files are - consistent with the source code. - This is a validation step to ensure that the documentation accurately reflects the example code. - This task is executed automatically via the [GitHub workflow][check-code-embedding]. - -4. **`buildSite`** — building the documentation site using Hugo. - The site is generated in the [_preview/](./_preview) directory. - -5. **`runSite`** — running a local Hugo server to preview the documentation site. - This allows you to view the documentation in a web browser during development. - -6. **`installDependencies`** — installing the Node dependencies for the preview site. - Tasks related to Hugo depend on this task. It is not meant to be run manually. - -## Paths in the scripts - -The shell [scripts](./_script) used by the Gradle build assume that **this** `docs/` -directory is the current working directory. - -So when you start working with the documentation, make sure to `cd` into -it before running any of the scripts or Gradle tasks. - -## Including example sources - -It is done in the [`settings.gradle.kts`](settings.gradle.kts) file via `includeBuild` directive. -If you add another example project, please remember to update -the [`settings.gradle.kts`](settings.gradle.kts) file. - -## Linking to the main project build - -The example projects share the following directories and files with -the main code project via symlinks: - * `buildSrc` - * `gradle.properties` - * `gradlew` - * `gradlew.bat` - -When you add an example project, make sure to create the necessary symlinks to -these files and directories. - -[check-code-embedding]: ../.github/workflows/check-code-embedding.yml -[main-documentation]: https://github.com/SpineEventEngine/documentation/ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..bf20bcadef --- /dev/null +++ b/docs/README.md @@ -0,0 +1,22 @@ +# Spine Validation — `docs/` module + +This directory hosts the source of the Spine Validation documentation. +It is a Hugo project supplemented by Gradle wiring and a Go-based +code-embedding tool. The content under `content/` and `data/` is the +contributor-editable source; the rest of the directories — `_preview/`, +`_examples/`, `_time/`, `_settings/`, `_script/`, `_bin/`, `_options/` — +support local rendering, code embedding, and the example projects the +documentation references. + +The `docs/` module is a **staging area**, not a published site. Content +under `content/` is merged into the main documentation project at +[SpineEventEngine/documentation][main-documentation] and published from +there to the spine.io website. + +For the full technical description of the documentation pipeline — the +Gradle tasks, the embedded-examples mechanism, the external tooling, and +the recurring contributor procedures — see the in-repository overview at +[content/docs/validation/developer/documentation/_index.md][overview]. + +[main-documentation]: https://github.com/SpineEventEngine/documentation +[overview]: content/docs/validation/developer/documentation/_index.md From 82c9c09349c5b17994720ca365c628c0e8fb3e13 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:11:18 +0100 Subject: [PATCH 18/40] Improve wording of tooling and procedures --- .../developer/documentation/procedures.md | 37 +++++++++++++------ .../developer/documentation/tooling.md | 13 ++++--- 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index 90f0b42d0f..f1c4f3282a 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -218,25 +218,39 @@ means rebuilding the binaries from the [embed-code-go][embed-code-go] source repository and replacing the artifacts. 1. Clone [embed-code-go][embed-code-go] (or update an existing clone) and - check out the release or commit to ship. + check out the release or commit to ship. The Go version required by + the project is declared in its `go.mod`; the upstream README documents + Go 1.22.1 as the minimum. -2. Build the three binaries that this repository ships. From the - `embed-code-go` clone, with the Go toolchain on the `PATH`: +2. From the project root of the `embed-code-go` clone, cross-compile the + three binaries that this repository ships. The command sequence is + the one documented under [Building from sources][embed-code-build] in + the upstream README: ```bash - GOOS=linux GOARCH=amd64 go build -o embed-code-linux ./cmd/... - GOOS=darwin GOARCH=amd64 go build -o embed-code-macos ./cmd/... - GOOS=windows GOARCH=amd64 go build -o embed-code-windows.exe ./cmd/... + mkdir -p bin && \ + GOOS=darwin GOARCH=amd64 go build -trimpath -o bin/embed-code-macos main.go && \ + GOOS=windows GOARCH=amd64 go build -trimpath -o bin/embed-code-windows.exe main.go && \ + GOOS=linux GOARCH=amd64 go build -trimpath -o bin/embed-code-linux main.go ``` - Replace the build target paths with whatever the upstream `README` - prescribes if it differs from `./cmd/...`. + The `-trimpath` flag strips absolute file paths from stack traces in + the binaries. 3. Copy the produced binaries into `docs/_bin/`, replacing the existing - files of the same names. + files of the same names: -4. Make sure the macOS and Linux binaries are executable - (`chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux`). + ```bash + cp bin/embed-code-linux /docs/_bin/ + cp bin/embed-code-macos /docs/_bin/ + cp bin/embed-code-windows.exe /docs/_bin/ + ``` + +4. Make sure the macOS and Linux binaries are executable: + + ```bash + chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux + ``` 5. Verify that the new binaries still produce the same embedded output the repository expects: @@ -299,3 +313,4 @@ source repository and replacing the artifacts. [doc-guidelines]: https://github.com/SpineEventEngine/validation/blob/master/.agents/documentation-guidelines.md [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go +[embed-code-build]: https://github.com/SpineEventEngine/embed-code-go#building-from-sources diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md index 83dbb726a2..fec78626db 100644 --- a/docs/content/docs/validation/developer/documentation/tooling.md +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -18,9 +18,8 @@ pinned. The step-by-step recipes for updating each live in [site-commons][site-commons] is the shared Hugo theme and layout library used by the documentation sites of Spine projects. It provides the navigation chrome, the sidenav rendering that consumes the -[`sidenav.yml`](../../../../data/docs/validation/2-0-0-snapshot/sidenav.yml) -files, code-highlighting partials, and other Hugo components that are -common across Spine sites. +[`sidenav.yml`][sidenav-yml] files, code-highlighting partials, and other +Hugo components that are common across Spine sites. It is consumed as a Hugo module. Two files wire it in: @@ -77,9 +76,9 @@ verification steps (preview, sanity check). `:docs:embedCode` and `:docs:checkSamples`. It reads the `` elements described in "[Embedded examples](embedded-examples.md)", resolves each `file` reference against the source roots in -[`_settings/embed-code.yml`](../../../../_settings/embed-code.yml), and -either rewrites the fenced code block beneath the element (`-mode="embed"`) -or fails non-zero on drift (`-mode="check"`). +[`_settings/embed-code.yml`][embed-code-yml], and either rewrites the +fenced code block beneath the element (`-mode="embed"`) or fails non-zero +on drift (`-mode="check"`). The tool is consumed as **prebuilt binaries checked into the repository**, not as a Go module or downloaded artifact. The binaries live under @@ -132,5 +131,7 @@ expects. [site-commons]: https://github.com/SpineEventEngine/site-commons [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates +[sidenav-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml +[embed-code-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/_settings/embed-code.yml [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go [hugo-install]: https://gohugo.io/installation/ From 472b25069971ab4afb837a4ff89b83175b391f21 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:14:50 +0100 Subject: [PATCH 19/40] Simplify `embed-code-go` update description --- .../developer/documentation/procedures.md | 49 ++++++------------- .../developer/documentation/tooling.md | 12 +++-- 2 files changed, 21 insertions(+), 40 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index f1c4f3282a..c76b524160 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -213,46 +213,25 @@ in this repository. ## Updating `embed-code-go` -The tool is consumed as prebuilt binaries under `docs/_bin/`. Updating -means rebuilding the binaries from the [embed-code-go][embed-code-go] -source repository and replacing the artifacts. +The tool is consumed as prebuilt binaries under `docs/_bin/`. The +authoritative copies are published by the upstream project under +[`embed-code-go/bin`][embed-code-bin]. We do *not* build the tool as +part of the Validation documentation build — see the upstream repository +for any build, test, or release questions. -1. Clone [embed-code-go][embed-code-go] (or update an existing clone) and - check out the release or commit to ship. The Go version required by - the project is declared in its `go.mod`; the upstream README documents - Go 1.22.1 as the minimum. +1. From [`embed-code-go/bin`][embed-code-bin], download the three + binaries on the branch or tag you want to ship: + `embed-code-linux`, `embed-code-macos`, `embed-code-windows.exe`. -2. From the project root of the `embed-code-go` clone, cross-compile the - three binaries that this repository ships. The command sequence is - the one documented under [Building from sources][embed-code-build] in - the upstream README: +2. Replace the files of the same names under `docs/_bin/`. - ```bash - mkdir -p bin && \ - GOOS=darwin GOARCH=amd64 go build -trimpath -o bin/embed-code-macos main.go && \ - GOOS=windows GOARCH=amd64 go build -trimpath -o bin/embed-code-windows.exe main.go && \ - GOOS=linux GOARCH=amd64 go build -trimpath -o bin/embed-code-linux main.go - ``` - - The `-trimpath` flag strips absolute file paths from stack traces in - the binaries. - -3. Copy the produced binaries into `docs/_bin/`, replacing the existing - files of the same names: - - ```bash - cp bin/embed-code-linux /docs/_bin/ - cp bin/embed-code-macos /docs/_bin/ - cp bin/embed-code-windows.exe /docs/_bin/ - ``` - -4. Make sure the macOS and Linux binaries are executable: +3. Make sure the macOS and Linux binaries are executable: ```bash chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux ``` -5. Verify that the new binaries still produce the same embedded output +4. Verify that the new binaries still produce the same embedded output the repository expects: ```bash @@ -263,8 +242,8 @@ source repository and replacing the artifacts. whitespace, …), run `./gradlew :docs:embedCode` and inspect the diff before committing. -6. Commit the updated binaries under `docs/_bin/` with a message that - names the upstream version or commit. +5. Commit the updated binaries under `docs/_bin/` with a message that + names the upstream commit they were pulled from. ## Building the documentation locally @@ -313,4 +292,4 @@ source repository and replacing the artifacts. [doc-guidelines]: https://github.com/SpineEventEngine/validation/blob/master/.agents/documentation-guidelines.md [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go -[embed-code-build]: https://github.com/SpineEventEngine/embed-code-go#building-from-sources +[embed-code-bin]: https://github.com/SpineEventEngine/embed-code-go/tree/master/bin diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md index fec78626db..2c66735cc4 100644 --- a/docs/content/docs/validation/developer/documentation/tooling.md +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -90,11 +90,12 @@ not as a Go module or downloaded artifact. The binaries live under | `embed-code-macos` | `_script/check-samples` locally; `_script/embed-code` always. | | `embed-code-windows.exe` | Currently not selected by either script. | -There is no version string recorded in this repository. Updating to a new -release of `embed-code-go` means rebuilding the binaries from its source -repository for each target platform and replacing the artifacts under -`docs/_bin/`. The step-by-step recipe is "Updating `embed-code-go`" in -"[Procedures](procedures.md)". +There is no version string recorded in this repository, and the +documentation build does *not* compile the tool. Updating to a new +release means downloading the corresponding binaries from +[`embed-code-go/bin`][embed-code-bin] in the upstream repository and +replacing the files under `docs/_bin/`. The step-by-step recipe is +"Updating `embed-code-go`" in "[Procedures](procedures.md)". ## Hugo and the Node toolchain @@ -134,4 +135,5 @@ expects. [sidenav-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/data/docs/validation/2-0-0-snapshot/sidenav.yml [embed-code-yml]: https://github.com/SpineEventEngine/validation/blob/master/docs/_settings/embed-code.yml [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go +[embed-code-bin]: https://github.com/SpineEventEngine/embed-code-go/tree/master/bin [hugo-install]: https://gohugo.io/installation/ From 5c2249675ed33923f8a37e0d21db5ffd3166c00c Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:17:01 +0100 Subject: [PATCH 20/40] Update Claude memory --- .../memory/MEMORY.md | 1 + ...ack_do_not_replicate_upstream_tool_docs.md | 24 +++++++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md index 6a454d5eba..ece78d07fc 100644 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md @@ -1 +1,2 @@ - [Do not use backticks around "spine.io"](feedback_spine_io_no_backticks.md) — render spine.io as plain prose or a link, never as code. +- [Do not replicate upstream tool documentation](feedback_do_not_replicate_upstream_tool_docs.md) — link to upstream READMEs for external tools; don't restate build/release recipes in this repo. diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md new file mode 100644 index 0000000000..ee70675465 --- /dev/null +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md @@ -0,0 +1,24 @@ +--- +name: Do not replicate upstream tool documentation in Validation docs +description: When the Validation docs touch an external tool (embed-code-go, site-commons, …), point at the upstream README — don't restate build/test/release recipes. +type: feedback +--- + +When the Validation documentation describes an external tool — for example +`embed-code-go` or `site-commons` — link to the upstream README for build, +test, and release details. Do not restate those instructions in this repo's +docs. + +**Why:** Upstream is the source of truth and changes independently. Copying +its recipes here creates drift the moment upstream changes its build +command, Go version requirement, or output paths. The user specifically +called this out after I had inlined the full `embed-code-go` cross-compile +sequence into "Procedures" — they pointed out that the Validation build does +not compile `embed-code-go`, so a fetch-and-drop recipe is the only thing +this repo should document. + +**How to apply:** For each external tool, write what *this* repository does +with it (where binaries land, which file pins the version, which Gradle +task consumes it) and link to the upstream README/section for everything +else. Default to "fetch the prebuilt artifact" over "build from source" +when the upstream publishes binaries. From 7c87f987e8774b71381b429cc13c000204a12753 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:19:50 +0100 Subject: [PATCH 21/40] Update Claude memory --- .../feedback_repo_name_links_backticked.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md new file mode 100644 index 0000000000..e45d4d1323 --- /dev/null +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md @@ -0,0 +1,25 @@ +--- +name: Backtick tool/repo names when used as link text to their repository +description: In Validation docs, render repo/tool identifiers (site-commons, embed-code-go, …) as inline code when they appear as link text pointing to their repository. +type: feedback +--- + +When a repo or tool identifier — for example `site-commons`, `embed-code-go`, +or a similar slug — appears as Markdown link text whose target is the +project's repository, format the link text as inline code: + +- Yes: `[`site-commons`][site-commons]` +- No: `[site-commons][site-commons]` + +**Why:** These are identifiers (repo names, package names, executable +names), so the documentation guidelines' rule of "format file and directory +names as code" extends naturally. Reviewers explicitly asked for this after +I had left such link text unformatted. + +**How to apply:** When you introduce a new link to one of these +repositories — or to any similarly named tool — wrap the visible link text +in backticks. Contrast with brand/site names like spine.io (see +"Do not use backticks around spine.io"), which stay plain prose. + +In tables and other places where the same name appears outside a link, the +existing rule still applies: format identifiers as inline code. From ae3c5cc3d97438f12be8863725667ce8359cddf8 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:20:08 +0100 Subject: [PATCH 22/40] Add backticks around `site-commons` and `embed-code-go` repo links --- .../docs/validation/developer/documentation/tooling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md index 2c66735cc4..c5398517f3 100644 --- a/docs/content/docs/validation/developer/documentation/tooling.md +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -7,7 +7,7 @@ headline: Documentation # External tooling The documentation build leans on three external pieces of tooling: the -[site-commons][site-commons] Hugo theme, the [embed-code-go][embed-code-go] +[`site-commons`][site-commons] Hugo theme, the [`embed-code-go`][embed-code-go] tool, and the Hugo + Node toolchain that drives the static-site build. This page documents what each is, how it is wired into the build, and where it is pinned. The step-by-step recipes for updating each live in @@ -15,7 +15,7 @@ pinned. The step-by-step recipes for updating each live in ## `site-commons` -[site-commons][site-commons] is the shared Hugo theme and layout library +[`site-commons`][site-commons] is the shared Hugo theme and layout library used by the documentation sites of Spine projects. It provides the navigation chrome, the sidenav rendering that consumes the [`sidenav.yml`][sidenav-yml] files, code-highlighting partials, and other @@ -72,7 +72,7 @@ verification steps (preview, sanity check). ## `embed-code-go` -[embed-code-go][embed-code-go] is the command-line tool that powers +[`embed-code-go`][embed-code-go] is the command-line tool that powers `:docs:embedCode` and `:docs:checkSamples`. It reads the `` elements described in "[Embedded examples](embedded-examples.md)", resolves each `file` reference against the source roots in From f5f8b361389f73918a2c982d0fe0888b347be377 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:20:34 +0100 Subject: [PATCH 23/40] Update Claude memory --- .../-Users-sanders-Projects-Spine-validation/memory/MEMORY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md index ece78d07fc..5e02c3b45c 100644 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md +++ b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md @@ -1,2 +1,3 @@ - [Do not use backticks around "spine.io"](feedback_spine_io_no_backticks.md) — render spine.io as plain prose or a link, never as code. - [Do not replicate upstream tool documentation](feedback_do_not_replicate_upstream_tool_docs.md) — link to upstream READMEs for external tools; don't restate build/release recipes in this repo. +- [Backtick repo/tool names when used as link text to their repo](feedback_repo_name_links_backticked.md) — render `site-commons`, `embed-code-go`, etc. as inline code when they are the visible text of a link to the project's repository. From b257ea38042d35bfa98523428dc59902ec8542b7 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:25:09 +0100 Subject: [PATCH 24/40] Simplify the reference to the Documentation repository --- .../docs/validation/developer/documentation/_index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md index e0182d7416..c41dcdb7ac 100644 --- a/docs/content/docs/validation/developer/documentation/_index.md +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -12,9 +12,8 @@ the build, how source code is embedded into pages, which external tools the build depends on, and the recurring procedures contributors need to perform. The `docs/` module is a *staging area*, not a published site. The pages and -data under it are merged into the main documentation project -([SpineEventEngine/documentation][main-documentation]) and published from -there to the [spine.io][spine-io] website. The build wiring on this page +data under it are merged into the [main documentation project][main-documentation] +and published from there to the [spine.io][spine-io] website. The build wiring on this page exists to let contributors preview, validate, and iterate on the content of this repository before that merge happens. From c90f1ccb38041f3c0aedb748e60f20d8619505b9 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:40:57 +0100 Subject: [PATCH 25/40] Remove `_options` directory --- docs/README.md | 2 +- docs/_options/options.proto | 1566 ----------------- .../developer/documentation/_index.md | 1 - 3 files changed, 1 insertion(+), 1568 deletions(-) delete mode 100644 docs/_options/options.proto diff --git a/docs/README.md b/docs/README.md index bf20bcadef..5fbba1de6c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ This directory hosts the source of the Spine Validation documentation. It is a Hugo project supplemented by Gradle wiring and a Go-based code-embedding tool. The content under `content/` and `data/` is the contributor-editable source; the rest of the directories — `_preview/`, -`_examples/`, `_time/`, `_settings/`, `_script/`, `_bin/`, `_options/` — +`_examples/`, `_time/`, `_settings/`, `_script/`, `_bin/` — support local rendering, code embedding, and the example projects the documentation references. diff --git a/docs/_options/options.proto b/docs/_options/options.proto deleted file mode 100644 index 31f02bfa67..0000000000 --- a/docs/_options/options.proto +++ /dev/null @@ -1,1566 +0,0 @@ -/* - * Copyright 2024, TeamDev. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Redistribution and use in source and/or binary forms, with or without - * modification, must retain the above copyright notice and the following - * disclaimer. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ -syntax = "proto3"; - -// API Note on Packaging -// --------------------- -// We do not define the package for this file to allow shorter options for user-defined types. -// This allows to write: -// -// option (internal) = true; -// -// instead of: -// -// option (spine.base.internal) = true; -// - -// Custom Type Prefix Option -// ------------------------- -// The custom `type_url_prefix` option allows to define specify custom type URL prefix for messages -// defined in a proto file. This option is declared in this file. Other proto files must import -// `options.proto` to be able to specify custom type URL prefix. -// -// It is recommended that the import statement is provided before the line with `type_url_prefix` -// option to make it obvious that custom option is defined in the imported file. -// -// For example: -// -// syntax = "proto3"; -// -// package my.package; -// -// import "spine/options.proto"; -// -// option (type_url_prefix) = "type.example.org"; -// - -option (type_url_prefix) = "type.spine.io"; -option java_multiple_files = true; -option java_outer_classname = "OptionsProto"; -option java_package = "io.spine.option"; - -import "google/protobuf/descriptor.proto"; - -// -// Reserved Range of Option Field Numbers -// -------------------------------------- -// Spine Options use the range of option field numbers from the internal range reserved for -// individual organizations. For details of custom Protobuf options and this range please see: -// -// https://developers.google.com/protocol-buffers/docs/proto#customoptions -// -// The whole range reserved for individual organizations is 50000-99999. -// The range used by Spine Options is 73812-75000. -// In order to prevent number collision with custom options used by a project based on Spine, -// numbers for custom options defined in this project should be in the range 50000-73811 or -// 75001-99999. -// - -extend google.protobuf.FieldOptions { - - // Field Validation Constraints - //----------------------------- - // For constraints defined via message-based types, please see documentation of corresponding - // message types. - // - - // The option to mark a field as required. - // - // When this option is set: - // - // 1. For message or enum fields, the field must be set to a non-default instance. - // 2. For `string` and `bytes` fields, the value must be set to a non-empty string or an array. - // 3. For repeated fields and maps, at least one element must be present. - // - // Other field types are not supported by the option. - // - // Unlike the `required` keyword in Protobuf 2, this option does not affect message - // serialization or deserialization. Even if a message content violates the requirement - // set by the option, it would still be a valid message for the Protobuf library. - // - // Example: Using `(required)` field validation constraint. - // - // message MyOuterMessage { - // MyMessage field = 1 [(required) = true]; - // } - // - bool required = 73812; - - // See `IfMissingOption` - IfMissingOption if_missing = 73813; - - // Reserved 73814 and 73815 for deleted options `decimal_max` and `decimal_min`. - - // A higher boundary to the range of values of a number. - MaxOption max = 73816; - - // A lower boundary to the range of values of a number. - MinOption min = 73817; - - // 73818 reserved for the (digits) option. - - // 73819 reserved for the (when) option. - - // See `PatternOption`. - PatternOption pattern = 73820; - - // Enables in-depth validation for fields that refer to a message. - // - // This option applies only to fields that reference a message: - // - // 1. Singular message fields. - // 2. Repeated fields of message types. - // 3. Map fields with message types as values. - // - // When set to `true`, the field is valid only if its value satisfies the validation - // constraints defined in the corresponding message type: - // - // 1. For singular message fields: the message must meet its constraints. - // - // Note: default instances are considered valid even if the message has required fields. - // In such cases, it is unclear whether the field is set with an invalid instance or - // simply unset. - // - // Example: - // - // ``` - // // Note that the default instance of `Address` is not valid because the `value` field - // // is mandatory. - // message Address { - // string value = 1 [(required) = true]; - // } - // - // // However, the default instance of `Address` in `Student.address` is valid, despite - // // having `(validate)` constraint that forces the message to meet its constraints. - // // Since the `address` field is optional for `Student`, `(validate)` would allow - // // default instances for this field treating them as "no value set". - // message Student { - // Address address = 1 [(validate) = true]; // implicit `(required) = false`. - // } - // - // // Make the validated field required to avoid this behavior. In this case, `(validate)` - // // continues to bypass default instances, but the `(required)` option will report them. - // message Student { - // Address address = 1 [(validate) = true, (required) = true]; - // } - // ``` - // - // 2. For repeated fields: every element in the repeated field must meet the constraints - // of its message type. - // - // Example: - // - // ``` - // // Note that the default instance of `PhoneNumber` is not valid because the `value` - // // field is mandatory. - // message PhoneNumber { - // string value = 1 [(required) = true, (pattern).regex = "^\+?[0-9\s\-()]{1,30}$"]; - // } - // - // // In contrast to singular fields, the default instances in `repeated` will also be - // // reported by the `(validate)` constraint, with those that do not match the pattern. - // message Student { - // repeated PhoneNumber number = 1 [(validate) = true]; - // } - // ``` - // - // 3. For map fields: each value in the map must meet the constraints of message type. - // Note: Protobuf does not allow messages to be used as map keys. - // - // Example: - // - // ``` - // // Note that the default instance of `PhoneNumber` is not valid because the `value` - // // field is mandatory. - // message PhoneNumber { - // string value = 1 [(required) = true, (pattern).regex = "^\+?[0-9\s\-()]{1,30}$"]; - // } - // - // // In contrast to singular fields, the default instances in `map` values will also be - // // reported by the `(validate)` constraint, with those that do not match the pattern. - // message Contacts { - // map map = 1 [(validate) = true]; - // } - // ``` - // - // If the field contains `google.protobuf.Any`, the option will first attempt to unpack - // the enclosed message, and only then validate it. However, unpacking is not always possible: - // - // 1. The default instance of `Any` is always valid because there is nothing to unpack - // and validate. - // 2. Instances with type URLs that are unknown to the application are also valid. - // - // Unpacking requires a corresponding Java class to deserialize the message, but if - // the application does not recognize the type URL, it has no way to determine which - // class to use. - // - // Such may happen when the packed message comes from a newer app version, an external - // system, or is simply not included in the application’s dependencies. - // - bool validate = 73821; - - // See `IfInvalidOption`. - IfInvalidOption if_invalid = 73822 [deprecated = true]; - - // See `GoesOption`. - GoesOption goes = 73823; - - // Indicates that a field can only be set once. - // - // This option allows the target field to accept assignments only if one of the following - // conditions is met: - // - // 1. The current field value is the default for its type. - // Refer to the official docs on default values: https://protobuf.dev/programming-guides/proto3/#default. - // 2. The current field value equals to the proposed new value. - // - // The option can be applied to the following singular field types: - // - // - any message or enum type; - // - any numeric type; - // - `bool`, `string` and `bytes`. - // - // Repeated fields, maps, and fields with explicit `optional` cardinality are not supported. - // Such declarations will lead to build-time errors. For more information on field cardinality, - // refer to the official docs: https://protobuf.dev/programming-guides/proto3/#field-labels. - // - // Assigning a value to a message field can be done in various ways in the generated code. - // It depends on the target language and specific implementation of `protoc`. This option - // doesn't enforce field immutability at the binary representation level. Also, it does not - // prevent the use of Protobuf utilities that can construct new messages without using field - // setters or properties. The primary purpose of this option is to support standard use cases, - // such as assigning values through setters or retrieving them during data merging. - // - // For example, let's take a look on how it works for the generated Java code. The following - // use cases are supported and validated by the option: - // - // 1. Assigning a field value using the field setter. - // 2. Assigning a field value using the field descriptor. - // 3. Merging data from another instance of the message class. - // 4. Merging data from a message's binary representation. - // 5. Merging specific fields (available for Message fields). - // - // Unsupported Java use cases include: - // - // 1. Constructing a message using the `DynamicMessage` class. - // 2. Merging data from messages provided by third-party Protobuf implementations. - // 3. Clearing a specific field or an entire message. - // - // For unsupported scenarios, the option performs no validation. It does not throw errors - // or print warnings. - // - // A typical use case involves a field, such as an ID, which remains constant throughout - // the lifecycle of an entity. - // - // Example: using `(set_once)` field validation constraint. - // - // message User { - // UserId id = 1 [(set_once) = true]; - // } - // - // Once set, the `id` field cannot be changed. - // - // Use `(if_set_again).error_msg` option to specify a custom error message that will be used for - // composing the error upon attempting to re-assign the field value. Refer to the documentation - // for the corresponding option for an example of its usage. - // - bool set_once = 73824; - - // The option to enforce uniqueness for collection fields. - // - // When the option is set to `true`, the behavior is as follows: - // - // 1. For `repeated` fields: all elements must be unique. - // 2. For `map` fields: while the map keys are inherently unique, all associated values - // must also be unique. - // - // Other field types are not supported. - // - // Uniqueness is determined by comparing the elements themselves, using their full equality. - // For example, in Java, it is defined by the `equals()` method. No special cases are applied, - // such as comparing only specific fields like IDs. - // - // Example: using `(distinct)` constraint for a `repeated` field. - // - // message Blizzard { - // - // // All snowflakes must be unique in this blizzard. - // // - // // Attempting to add a snowflake that is equal to an existing one would result - // // in a constraint violation error. - // // - // repeated Snowflake snowflakes = 1 [(distinct) = true]; - // } - // - // Example: using `(distinct)` constraint for a `map` field. - // - // message UniqueEmails { - // - // // The associated email values must be unique. - // // - // // Attempting to add a key/value pair where the `Email` value duplicates - // // an existing one would result in a constraint violation error. - // // - // map emails = 1 [(distinct) = true]; - // } - // - bool distinct = 73825; - - // Reserved 73826 for deleted `range` option, which had `string` type. - - // Defines the error message used if a `set_once` field is set again. - // - // Applies only to the fields marked as `set_once`. - // - IfSetAgainOption if_set_again = 73827; - - // Defines the error message used if a `distinct` field has duplicates. - // - // Applies only to the repeated fields marked as `distinct`. - // - IfHasDuplicatesOption if_has_duplicates = 73828; - - // The option to indicate that a numeric field is required to have a value which belongs - // to the specified bounded range. - // - // For unbounded ranges, please use `(min)` and `(max) options. - // - RangeOption range = 73829; - - // Reserved 73830 to 73849 for future validation options. - - // API Annotations - //----------------- - - // Indicates a field which is internal to Spine, not part of the public API, and should not be - // used by users of the framework. - // - // If you plan to implement an extension of the framework, which is going to be - // wired into the framework, you may use the internal parts. Please consult with the Spine - // team, as the internal APIs do not have the same stability API guarantee as public ones. - // - bool internal = 73850; - - // Reserved 73851 for the deleted SPI option. - - // Indicates a field that can change at any time, and has no guarantee of API stability and - // backward-compatibility. - // - // Usage guidelines: - // 1. This annotation is used only on public API. Internal interfaces should not use it. - // 2. This annotation can only be added to new API. Adding it to an existing API is considered - // API-breaking. - // 3. Removing this annotation from an API gives it stable status. - // - bool experimental = 73852; - - // Signifies that a public API is subject to incompatible changes, or even removal, in a future - // release. - // - // An API bearing this annotation is exempt from any compatibility guarantees made by its - // containing library. Note that the presence of this annotation implies nothing about the - // quality of the API in question, only the fact that it is not "API-frozen." - // It is generally safe for applications to depend on beta APIs, at the cost of - // some extra work during upgrades. - // - bool beta = 73853; - - // Marks an entity state field as column. - // - // The column fields are stored separately from the entity record and can be specified as - // filtering criteria during entity querying. - // - // The column field should be declared as follows: - // - // message UserProfile { - // ... - // int32 year_of_registration = 8 [(column) = true]; - // } - // - // The `year_of_registration` field value can then be used as query parameter when reading - // entities of `UserProfile` type from the server side. - // - // The value of a column field can be updated in two ways: - // - // 1. In the receptors of the entity, just like any other part of entity state. - // 2. Using the language-specific tools like `EntityWithColumns` interface in Java. - // - // All column fields are considered optional by the framework. - // - // Currently, only entities of projection and process manager type are - // eligible for having columns (see `EntityOption`). - // For all other message types the column declarations are ignored. - // - // The `repeated` and `map` fields cannot be columns. - // - bool column = 73854; - - // Reserved 73855 to 73890 for future options. - - // Reserved 73900 for removed `by` option. -} - -extend google.protobuf.OneofOptions { - - // Deprecated: use the `(choice)` option instead. - bool is_required = 73891 [deprecated = true]; - - // Controls whether a `oneof` group must always have one of its fields set. - ChoiceOption choice = 73892; - - // Reserved 73893 to 73899 for future options. -} - -extend google.protobuf.MessageOptions { - - // Validation Constraints - //------------------------ - - // The default validation error message. - // - // Please note, this option is intended for INTERNAL USE only. It applies to message types - // that extend `FieldOptions` and is not intended for external usage. - // - // If a validation option detects a constraint violation and no custom error message is defined - // for that specific option, it will fall back to the message specified by `(default_message)`. - // - // For example, here is how to declare the default message for `(goes)` option: - // - // ``` - // message GoesOption { - // // The default error message. - // option (default_message) = "The field `${goes.companion}` must also be set when `${field.path}` is set."; - // } - // ``` - // - // Note: The placeholders available within `(default_message)` depend solely on the particular - // validation option that uses it. Each option may define its own set of placeholders, or none. - // - string default_message = 73901 [(internal) = true]; - - // Deprecated: use the `(require)` option instead. - string required_field = 73902 [deprecated = true]; - - // See `EntityOption`. - EntityOption entity = 73903; - - // An external validation constraint for a field. - // - // WARNING: This option is deprecated and is scheduled for removal in Spine v2.0.0. - // - // Allows to re-define validation constraints for a message when its usage as a field of - // another type requires alternative constraints. This includes definition of constraints for - // a message which does not have them defined within the type. - // - // A target field of an external constraint should be specified using a fully-qualified - // field name (e.g. `mypackage.MessageName.field_name`). - // - // Example: defining external validation constraint. - // - // package io.spine.example; - // - // // Defines a change in a string value. - // // - // // Both of the fields of this message are not `required` to be able to describe - // // a change from empty value to non-empty value, or from a non-empty value to - // // an empty string. - // // - // message StringChange { - // - // // The value of the field that's changing. - // string previous_value = 1; - // - // // The new value of the field. - // string new_value = 2; - // } - // - // // A command to change a name of a task. - // // - // // The task has a non-empty name. A new name cannot be empty. - // // - // message RenameTask { - // - // // The ID of the task to rename. - // string task_id = 1; - // - // // Instruction for changing the name. - // // - // // The value of `change.previous_value` is the current name of the task. - // // It cannot be empty. - // // - // // The value of `change.new_value` is the new name of the task. - // // It cannot be empty either. - // // - // StringChange change = 1 [(validate) = true]; - // } - // - // // External validation constraint for both fields of the `StringChange` message - // // in the scope of the `RenameTask` command. - // // - // message RequireTaskNames { - // option (constraint_for) = "spine.example.RenameTask.change"; - // - // string previous_value = 1 [(required) = true]; - // string new_value = 2 [(required) = true]; - // } - // - // NOTE: A target field for an external validation constraint must be have the option `(validate)` - // set to `true`. See the definition of the `RenameTask.change` field in the example - // above. If there is no such option defined, or it is set to `false`, the external - // constraint will not be applied. - // - // External validation constraints can be applied to fields of several types. - // To do so, separate fully-qualified references to these fields with comma. - // - // Example: external validation constraints for multiple fields. - // - // // External validation constraint for requiring a new value in renaming commands. - // message RequireNewName { - // option (constraint_for) = "spine.example.RenameTask.change," - // "spine.example.RenameProject.change,"; - // "spine.example.UpdateComment.text_change; - // - // string new_value = 1 [(required) = true]; - // } - // - // NOTE: An external validation constraint for a field must be defined only once. - // Spine Model Compiler does not check such an "overwriting". - // See the issue: https://github.com/SpineEventEngine/base/issues/318. - // - string constraint_for = 73904 [deprecated = true]; - - // Reserved 73905 to 73910 for future validation options. - - // API Annotations - //----------------- - - // Indicates a type usage of which is restricted in one of the following ways. - // - // 1. This type is internal to the Spine Event Engine framework. It is not a part of - // the public API, and must not be used by framework users. - // - // 2. The type is internal to a bounded context, artifact of which exposes the type to - // the outside world (presumably for historical reasons). - // - // The type with such an option can be used only inside the bounded context which declares it. - // - // The type must not be used neither for inbound (i.e. being sent to the bounded context - // which declares this type) nor for outbound communication (i.e. being sent by this - // bounded context outside). - // - // An attempt to violate these usage restrictions will result in a runtime error. - // - bool internal_type = 73911; - - // Indicates a file which contains elements of Service Provider Interface (SPI). - bool SPI_type = 73912; - - // Indicates a public API that can change at any time, and has no guarantee of - // API stability and backward-compatibility. - bool experimental_type = 73913; - - // Signifies that a public API is subject to incompatible changes, or even removal, - // in a future release. - bool beta_type = 73914; - - // Specifies a characteristic inherent in the the given message type. - // - // Example: using `(is)` message option. - // - // message CreateProject { - // option (is).java_type = "ProjectCommand"; - // - // // Remainder omitted. - // } - // - // In the example above, `CreateProject` message is a `ProjectCommand`. - // - // To specify a characteristic for every message in a `.proto` file, - // please use `(every_is)` file option. - // - // If both `(is)` and `(every_is)` options are applicable for a type, both are applied. - // - // When targeting Java, specify the name of a Java interface to be implemented by this - // message via `(is).java_type`. - // - IsOption is = 73915; - - // Reserved 73916 to 73921 for future API annotation options. - - // Reserved 73922 for removed `enrichment_for` option. - - // Specifies the natural ordering strategy for this type. - // - // Code generators should generate language-specific comparisons based on the field paths. - // - // Runtime comparators may use the reflection API to compare field values. - // - CompareByOption compare_by = 73923; - - // The constraint to require at least one of the fields or combinations of fields. - RequireOption require = 73924; - - // Reserved 73925 to 73938 for future options. - - // Reserved 73939 and 73940 for the deleted options `events` and `rejections`. -} - -extend google.protobuf.FileOptions { - - // Specifies a type URL prefix for all types within a file. - // - // This type URL will be used when packing messages into `Any`. - // See `any.proto` for more details. - // - string type_url_prefix = 73941; - - // Indicates a file which contains types usage of which is restricted. - // - // For more information on such restrictions please see the documentation of - // the type option called `internal_type`. - // - // If a file contains a declaration of a `service`, this option will NOT be applied to it. - // A service is not a data type, and therefore, this option does not apply to it. - // Internal services are not supported. - // - bool internal_all = 73942; - - // Indicates a file which contains elements of Service Provider Interface (SPI). - // - // This option applies to messages, enums, and services. - // - bool SPI_all = 73943; - - // Indicates a file declaring public data type API which that can change at any time, - // has no guarantee of API stability and backward-compatibility. - // - // If a file contains a declaration of a `service`, this option will NOT be applied to it. - // A service is not a data type, and therefore, this option does not apply to it. - // Experimental services are not supported. - // - bool experimental_all = 73944; - - // Signifies that a public data type API is subject to incompatible changes, or even removal, - // in a future release. - // - // If a file contains a declaration of a `service`, this option will NOT be applied to it. - // A service is not a data type, and therefore, this option does not apply to it. - // Beta services are not supported. - // - bool beta_all = 73945; - - // Specifies a characteristic common for all the message types in the given file. - // - // Example: marking all the messages using the `(every_is)` file option. - // ``` - // option (every_is).java_type = "ProjectCommand"; - // - // message CreateProject { - // // ... - // - // message WithAssignee { - // // ... - // } - // } - // - // message DeleteProject { /*...*/ } - // ``` - // - // In the example above, `CreateProject`, `CreateProject.WithAssignee`, and `DeleteProject` - // messages are `ProjectCommand`-s. - // - // To specify a characteristic for a single message, please use `(is)` message option. - // If both `(is)` and `(every_is)` options are applicable for a type, both are applied. - // - // When targeting Java, specify the name of a Java interface to be implemented by these - // message types via `(every_is).java_type`. - // - EveryIsOption every_is = 73946; - - // Reserved 73947 to 73970 for future use. -} - -extend google.protobuf.ServiceOptions { - - // Indicates that the service is a part of Service Provider Interface (SPI). - bool SPI_service = 73971; - - // Reserved 73971 to 73980. -} - -// Reserved 73981 to 74000 for other future Spine Options numbers. - -// -// Validation Option Types -//--------------------------- - -// Defines the error message used if a `required` field is not set. -// -// Applies only to the fields marked as `required`. -// -message IfMissingOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}`" - " of the type `${field.type}` must have a non-default value."; - - // A user-defined validation error format message. - // - // Use `error_msg` instead. - // - string msg_format = 1 [deprecated = true]; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.type}` – the fully qualified name of the field type. - // 3. `${parent.type}` – the fully qualified name of the validated message. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - // Example: using the `(if_missing)` option. - // - // message Student { - // Name name = 1 [(required) = true, - // (if_missing).error_msg = "The `${field.path}` field is mandatory for `${parent.type}`."]; - // } - // - string error_msg = 2; -} - -// Indicates that the numeric field must be greater than or equal to the specified value. -// -// The option supports all singular and repeated numeric fields. -// -message MinOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}`" - " must be ${min.operator} ${min.value}. The passed value: `${field.value}`."; - - // The string representation of the minimum field value. - // - // ## Integer and floating-point values - // - // A minimum value for an integer field must use an integer number. Specifying a decimal - // number is not allowed, even if it has no fractional part (e.g., `5.0` is invalid). - // - // A minimum value for a floating-point field must use a decimal separator (`.`), even if - // the value has no fractional part. An exponent part represented by `E` or `e`, followed - // by an optional sign and digits is allowed (e.g., `1.2E3`, `0.5e-2`). - // - // Example: defining minimum values for integer and floating-point fields. - // - // message Measurements { - // int32 temperature = 1 [(min).value = "0"]; - // uint32 mass = 2 [(min).value = "5"]; - // float degree = 3 [(min).value = "0.0"]; - // double angle = 4 [(min).value = "30.0"]; - // float pressure = 5 [(min).value = "950.0E-2"]; - // } - // - // ## Field Type Limitations - // - // A minimum value must not fall below the limits of the field type. - // - // Example: invalid values that fall below the field type limits. - // - // message OverflowMeasurements { - // float pressure = 1 [(min).value = "-5.5E38"]; // Falls below the `float` minimum. - // uint32 mass = 2 [(min).value = "-5"]; // Falls below the `uint32` minimum. - // } - // - // ## Field references - // - // Instead of numeric literals, you can reference another numeric field. - // At runtime, the field’s value will be used as the bound. Nested fields are supported. - // - // Example: defining minimum values using field references. - // - // message Measurements { - // - // int32 min_length = 1; - // int32 length = 2 [(min).value = "min_length"]; - // - // Limits limits = 3; - // int32 temperature = 4 [(min).value = "limits.min_temperature"]; - // float pressure = 5 [(min).value = "limits.min_pressure"]; - // } - // - // message Limits { - // int32 min_temperature = 1; - // float min_pressure = 2; - // } - // - // Note: Field type compatibility is not required in this case; the value is - // automatically converted. However, only numeric fields can be referenced. - // Repeated and map fields are not supported. - // - string value = 1; - - // Specifies if the field should be strictly greater than the specified minimum. - // - // The default value is false, i.e. the bound is inclusive. - // - bool exclusive = 2; - - // A user-defined validation error format message. - string msg_format = 3 [deprecated = true]; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.value}` - the field value. - // 2. `${field.path}` – the field path. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the validated message. - // 5. `${min.value}` – the specified minimum `value`. For referenced fields, the actual - // field value is also printed in round brackets along with the reference itself. - // 6. `${min.operator}` – if `exclusive` is set to `true`, this placeholder equals to ">". - // Otherwise, ">=". - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 4; -} - -// Indicates that the numeric field must be less than or equal to the specified value. -// -// The option supports all singular and repeated numeric fields. -// -message MaxOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}`" - " must be ${max.operator} ${max.value}. The passed value: `${field.value}`."; - - // The string representation of the maximum field value. - // - // ## Integer and floating-point values - // - // A maximum value for an integer field must use an integer number. Specifying a decimal - // number is not allowed, even if it has no fractional part (e.g., `5.0` is invalid). - // - // A maximum value for a floating-point field must use a decimal separator (`.`), even if - // the value has no fractional part. An exponent part represented by `E` or `e`, followed - // by an optional sign and digits is allowed (e.g., `1.2E3`, `0.5e-2`). - // - // Example: defining maximum values for integer and floating-point fields. - // - // message Measurements { - // int32 temperature = 1 [(max).value = "270"]; - // uint32 mass = 2 [(max).value = "1200"]; - // float degree = 3 [(max).value = "360.0"]; - // double angle = 4 [(max).value = "90.0"]; - // float pressure = 5 [(max).value = "1050.0E-2"]; - // } - // - // ## Field Type Limitations - // - // A maximum value must not exceed the limits of the field type. - // - // Example: invalid values that exceed the field type limits. - // - // message OverflowMeasurements { - // float pressure = 1 [(min).value = "5.5E38"]; // Exceeds the `float` maximum. - // int32 mass = 2 [(min).value = "2147483648"]; // Exceeds the `int32` maximum. - // } - // - // ## Field references - // - // Instead of numeric literals, you can reference another numeric field. - // At runtime, the field’s value will be used as the bound. Nested fields are supported. - // - // Example: defining maximum values using field references. - // - // message Measurements { - // - // int32 max_length = 1; - // int32 length = 2 [(max).value = "max_length"]; - // - // Limits limits = 3; - // int32 temperature = 4 [(max).value = "limits.max_temperature"]; - // float pressure = 5 [(max).value = "limits.max_pressure"]; - // } - // - // message Limits { - // int32 max_temperature = 1; - // float max_pressure = 2; - // } - // - // Note: Field type compatibility is not required in this case; the value is - // automatically converted. However, only numeric fields can be referenced. - // Repeated and map fields are not supported. - // - string value = 1; - - // Specifies if the field should be strictly less than the specified maximum - // - // The default value is false, i.e. the bound is inclusive. - // - bool exclusive = 2; - - // A user-defined validation error format message. - string msg_format = 3 [deprecated = true]; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.value}` - the field value. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the validated message. - // 5. `${max.value}` – the specified maximum `value`. For referenced fields, the actual - // field value is also printed in round brackets along with the reference itself. - // 6. `${max.operator}` – if `exclusive` is set to `true`, this placeholder equals to "<". - // Otherwise, "<=". - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 4; -} - -// A string field value must match the given regular expression. -// -// This option is applicable only to string fields, -// including those that are repeated. -// -// Example: using the `(pattern)` option. -// -// message CreateAccount { -// string id = 1 [(pattern).regex = "^[A-Za-z0-9+]+$", -// (pattern).error_msg = "ID must be alphanumerical in `${parent.type}`. Provided: `${field.value}`."]; -// } -// -message PatternOption { - - // The default error message. - option (default_message) = "The `${parent.type}.${field.path}` field" - " must match the regular expression `${regex.pattern}` (modifiers: `${regex.modifiers}`)." - " The passed value: `${field.value}`."; - - // The regular expression that the field value must match. - // - // Please use the Java regex dialect for the syntax baseline: - // https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html - // - // Note: in Java, regex patterns are not wrapped in explicit delimiters like in Perl or PHP. - // Instead, the pattern is provided as a string literal. Therefore, `/` symbol does not need - // to be escaped. - // - // The provided string literal is passed directly to the regex engine. So, it must be exactly - // what you would supply to the `java.util.regex.Pattern.compile()` method. - // - string regex = 1; - - reserved 2; - reserved "flag"; - - // Modifiers for this pattern. - Modifier modifier = 4; - - // A user-defined validation error format message. - string msg_format = 3 [deprecated = true]; - - // A user-defined validation error format message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.value}` - the field value. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the validated message. - // 5. `${regex.pattern}` – the specified regex pattern. - // 6. `${regex.modifiers}` – the specified modifiers, if any. For example, `[dot_all, unicode]`. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 5; - - // Regular expression modifiers. - // - // These modifiers are specifically selected to be supported in many implementation platforms. - // - message Modifier { - - // Enables the dot (`.`) symbol to match all the characters. - // - // By default, the dot does not match line break characters. - // - // May also be known in some platforms as "single line" mode and be encoded with - // the `s` flag. - // - bool dot_all = 1; - - // Allows to ignore the case of the matched symbols. - // - // For example, this modifier is specified, string `ABC` would be a complete match for - // the regex `[a-z]+`. - // - // On some platforms may be represented by the `i` flag. - // - bool case_insensitive = 2; - - // Enables the `^` (caret) and `$` (dollar) signs to match a start and an end of a line - // instead of a start and an end of the whole expression. - // - // On some platforms may be represented by the `m` flag. - // - bool multiline = 3; - - // Enables matching the whole UTF-8 sequences, - // - // On some platforms may be represented by the `u` flag. - // - bool unicode = 4; - - // Allows the matched strings to contain a full match to the pattern and some other - // characters as well. - // - // By default, a string only matches a pattern if it is a full match, i.e. there are no - // unaccounted for leading and/or trailing characters. - // - // This modifier is usually not represented programming languages, as the control over - // weather to match an entire string or only its part is provided to the user by other - // language means. For example, in Java, this would be the difference between methods - // `matches()` and `find()` of the `java.util.regex.Matcher` class. - // - bool partial_match = 5; - } -} - -// Specifies the message to show if a validated field happens to be invalid. -// -// It is applicable only to fields marked with `(validate)`. -// -message IfInvalidOption { - - // Do not specify error message for `(validate)`, it is no longer used by - // the validation library. - option deprecated = true; - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}` of the type" - " `${field.type}` is invalid. The field value: `${field.value}`."; - - // A user-defined validation error format message. - // - // Use `error_msg` instead. - // - string msg_format = 1 [deprecated = true]; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.value}` - the field value. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the field declaring type. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - // Example: using the `(if_invalid)` option. - // - // message Transaction { - // TransactionDetails details = 1 [(validate) = true, - // (if_invalid).error_msg = "The `${field.path}` field is invalid."]; - // } - // - string error_msg = 2; -} - -// Specifies that another field must be present if the option's target field is present. -// -// Unlike the `required_field` that handles combination of required fields, this option is useful -// when it is needed to say that an optional field makes sense only when another optional field -// is present. -// -// This option can be applied to the same field types as `(required)`, including both the -// target field and its companion. Supported field types are: -// -// - Messages and enums. -// - Repeated fields and maps. -// - `string` and `bytes`. -// -// Example: requiring mutual presence of optional fields. -// -// message ScheduledItem { -// ... -// spine.time.LocalDate date = 4; -// spine.time.LocalTime time = 5 [(goes).with = "date"]; -// } -// -message GoesOption { - - // The default error message. - option (default_message) = "The field `${goes.companion}` must also be set when `${field.path}`" - " is set in `${parent.type}`."; - - // The name of the companion field whose presence is required for this field to be valid. - string with = 1; - - // A user-defined validation error format message. - string msg_format = 2 [deprecated = true]; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.value}` – the field value. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the validated message. - // 5. `${goes.companion}` – the name of the companion specified in `with`. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 3; -} - -// Defines options of a message representing a state of an entity. -message EntityOption { - - // A type of an entity for state of which the message is defined. - enum Kind { - option allow_alias = true; - - // Reserved for errors. - KIND_UNKNOWN = 0; - - // The message is an aggregate state. - AGGREGATE = 1; - - // The message is a state of a projection (same as "view"). - PROJECTION = 2; - - // The message is a state of a view (same as "projection"). - VIEW = 2; - - // The message is a state of a process manager. - PROCESS_MANAGER = 3; - - // The message is a state of an entity, which is not of the type - // defined by other members of this enumeration. - ENTITY = 4; - } - - // The type of the entity. - Kind kind = 1; - - // The level of visibility of the entity to queries. - enum Visibility { - - // Default visibility is different for different types of entities: - // - for projections, "FULL" is default; - // - for aggregates, process managers, and other entities, "NONE" is default. - // - DEFAULT = 0; - - // The entity is not visible to queries. - NONE = 1; - - // Client-side applications can subscribe to updates of entities of this type. - SUBSCRIBE = 2; - - // Client-side applications can query this type of entities. - QUERY = 3; - - // Client-side applications can subscribe and query this type of entity. - FULL = 4; - } - - // The visibility of the entity. - // - // If not defined, the value of this option is `DEFAULT`. - // - Visibility visibility = 2; -} - -// Defines a common type for message types declared in the same proto file. -// -// The nature of the type depends on the target programming language. -// For example, the `java_type` property defines a name of the Java interface common -// to all message classes generated for the proto file having this option. -// -// The option triggers creation of the common type if the `generate` property is set to true. -// Otherwise, it is expected that the user provides the reference to an existing type. -// -message EveryIsOption { - - // Enables the generation of the common type. - // - // The default value is `false`. - // - bool generate = 1; - - // The reference to a Java top-level interface. - // - // The interface cannot be nested into a class or another interface. - // If a nested interface is provided, the code generation should fail the build process. - // - // The value may be a fully-qualified or a simple name. - // - // When a simple name is set, it is assumed that the interface belongs to - // the package of the generated message classes. - // - // If the value of the `generate` field is set to `false` the referenced interface must exist. - // Otherwise, a compilation error will occur. - // - // If the value of the `generate` field is set to `true`, the framework will - // generate the interface using the given name and the package as described above. - // - // The generated interface will extend `com.google.protobuf.Message` and - // will have no declared methods. - // - string java_type = 2; -} - -// Defines additional type for a message type in which this option is declared. -// -// The nature of the type depends on the target programming language. -// For example, the `java_type` property defines a name of the Java interface which -// the generated message class will implement. -// -message IsOption { - - // The reference to a Java top-level interface. - // - // The interface cannot be nested into a class or another interface. - // If a nested interface is provided, the code generation should fail the build process. - // - // The value may be a fully-qualified or a simple name. - // - // When a simple name is set, it is assumed that the interface belongs to - // the package of the generated message classes. - // - // The referenced interface must exist. Otherwise, a compilation error will occur. - // - string java_type = 1; -} - -// Defines the way to compare two messages of the same type to one another. -// -// Comparisons can be used to sort values. -// -// See the `(compare_by)` option. -// -message CompareByOption { - - // Field paths used for comparisons. - // - // The allowed field types are: - // - any number type; - // - `bool` (`false` is less than `true`); - // - `string` (in the order of respective Unicode values); - // - enumerations (following the order of numbers associated with each constant); - // - local messages (generated within the current build) marked with `(compare_by)`; - // - external messages (from dependencies), which either marked with `(compare_by)` - // OR have a comparator provided in `io.spine.compare.ComparatorRegistry`. - // - // Other types are not permitted. Repeated or map fields are not permitted either. - // Such declarations will lead to build-time errors. - // - // To refer to nested fields, separate the field names with a dot (`.`). - // No fields in the path can be repeated or maps. - // - // When multiple field paths are specified, comparison is executed in the order of reference. - // For example, specifying `["seconds", "nanos"]` makes the comparison mechanism prioritize - // the `seconds` field and refer to `nanos` only when `seconds` are equal. - // - // NOTE: When comparing fields with a message type, a non-set message is always less than - // a set message. But if a message is set to a default value, the comparison falls back to - // the field-wise comparison, i.e. number values are treated as zeros, `bool` — as `false`, - // and so on. - // - repeated string field = 1; - - // If true, the default order is reversed. For example, numbers are ordered from the greater to - // the lower, enums — from the last number value to the 0th value, etc. - bool descending = 2; -} - -// Defines the error message used if a `set_once` field is set again. -// -// Applies only to the fields marked as `set_once`. -// -message IfSetAgainOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}` of the type" - " `${field.type}` already has the value `${field.value}` and cannot be reassigned" - " to `${field.proposed_value}`."; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.type}` – the fully qualified name of the field type. - // 3. `${field.value}` – the current field value. - // 4. `${field.proposed_value}` – the value, which was attempted to be set. - // 5. `${parent.type}` – the fully qualified name of the validated message. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - // Example: using the `(set_once)` option. - // - // message User { - // UserId id = 1 [(set_once) = true, - // (if_set_again).error_msg = "A student ID is used as a permanent identifier within academic system, and cannot be re-assigned."]; - // } - // - string error_msg = 1; -} - -// Defines the error message used if a `distinct` field has duplicates. -// -// Applies only to the `repeated` and `map` fields marked with the `(distinct)` option. -// -message IfHasDuplicatesOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}` of the type" - " `${field.type}` must not contain duplicates." - " The duplicates found: `${field.duplicates}`."; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.type}` – the fully qualified name of the field type. - // 3. `${field.value}` – the field value (the whole collection). - // 4. `${field.duplicates}` – the duplicates found (elements that occur more than once). - // 5. `${parent.type}` – the fully qualified name of the validated message. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - // Example: using the `(distinct)` option. - // - // message Blizzard { - // repeated Snowflake = 1 [(distinct) = true, - // (if_has_duplicates).error_msg = "Every snowflake must be unique! The duplicates found: `${field.duplicates}`."]; - // } - // - string error_msg = 1; -} - -// Indicate that the numeric field must belong to the specified bounded range. -// -// For unbounded ranges, please use `(min)` and `(max) options. -// -// The option supports all singular and repeated numeric fields. -// -message RangeOption { - - // The default error message. - option (default_message) = "The field `${parent.type}.${field.path}` must be within" - " the following range: `${range.value}`. The passed value: `${field.value}`."; - - // The string representation of the range. - // - // A range consists of two bounds: a lower bound and an upper bound. These bounds are - // separated by either the `..` or ` .. ` delimiter. Each bound can be either open - // or closed. The format of the bounds and the valid values depend on the type of field. - // - // ## Bound Types - // - // - Closed bounds include the endpoint and are indicated using square brackets (`[`, `]`). - // Example: `[0..10]` represents values from 0 to 10, inclusive. - // - // - Open bounds exclude the endpoint and are indicated using parentheses (`(`, `)`). - // Example: `(0..10)` represents values strictly between 0 and 10. - // - // The lower bound must be less than or equal to the upper bound. - // - // ## Integer Fields - // - // A range for an integer field must use integer numbers. Specifying a decimal number - // is not allowed, even if it has no fractional part (e.g., `5.0` is invalid). - // - // Example: defining ranges for integer fields. - // - // message Measurements { - // int32 length = 1 [(range).value = "[0..100)"]; - // uint32 mass = 2 [(range).value = "(0..100]"]; - // } - // - // ## Floating-Point Fields - // - // A range for a floating-point field must use a decimal separator (`.`), even if the value - // has no fractional part. An exponent part represented by `E` or `e`, followed by an optional - // sign and digits is allowed (e.g., `1.2E3`, `0.5e-2`). - // - // Example: defining ranges for floating-point fields. - // - // message Measurements { - // float degree = 1 [(range).value = "[0.0 .. 360.0)"]; - // double angle = 2 [(range).value = "(0.0 .. 180.0)"]; - // float pressure = 3 [(range).value = "[950.0E-2 .. 1050.0E-2]"]; - // } - // - // ## Field Type Limitations - // - // A range must not exceed the limits of the field type. - // - // Example: invalid ranges that exceed the field type limits. - // - // message OverflowMeasurements { - // float price = 1 [(range).value = "[0, 5.5E38]"]; // Exceeds the `float` maximum. - // uint32 size = 2 [(range).value = "[-5; 10]"]; // Falls below the `uint32` minimum. - // } - // - // ## Field references - // - // Instead of numeric literals, you can reference another numeric field. - // At runtime, the field’s value will be used as the bound. Nested fields are supported. - // - // Example: defining ranges using field references. - // - // message Measurements { - // - // int32 max_length = 1; - // int32 length = 2 [(range).value = "[1 .. max_length"]; - // - // Limits limits = 3; - // int32 temperature = 4 [(range).value = "[limits.low_temp .. limits.high_temp]"]; - // } - // - // message Limits { - // int32 low_temp = 1; - // int32 high_temp = 2; - // } - // - // Note: Field type compatibility is not required in this case; the value is - // automatically converted. However, only numeric fields can be referenced. - // Repeated and map fields are not supported. - // - string value = 1; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${field.path}` – the field path. - // 2. `${field.value}` - the field value. - // 3. `${field.type}` – the fully qualified name of the field type. - // 4. `${parent.type}` – the fully qualified name of the validated message. - // 5. `${range.value}` – the specified range. For referenced fields, the actual - // field value is also printed in round brackets along with the reference itself. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 2; -} - -// Controls whether a `oneof` group must always have one of its fields set. -// -// Note that unlike the `(required)` constraint, this option supports any field types -// within the group cases. -// -message ChoiceOption { - - // The default error message. - option (default_message) = "The `oneof` group `${parent.type}.${group.path}` must" - " have one of its fields set."; - - // Enables or disables the requirement for the `oneof` group to have a value. - bool required = 1; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${group.path}` – the group path. - // 2. `${parent.type}` – the fully qualified name of the validated message. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 2; -} - -// Declares the field groups, at least one of which must have all of its fields set. -// -// Unlike the `(required)` field constraint, which requires the presence of -// a specific field, this option allows to specify alternative field groups. -// -message RequireOption { - - // The default error message. - option (default_message) = "The message `${message.type}` must have at least one of" - " the following field groups set: `${require.fields}`."; - - // A set of field groups, at least one of which must have all of its fields set. - // - // A field group can include one or more fields joined by the ampersand (`&`) symbol. - // `oneof` group names are also valid and can be used along with field names. - // Groups are separated using the pipe (`|`) symbol. - // - // The field type determines when the field is considered set: - // - // 1. For message or enum fields, it must have a non-default instance. - // 2. For `string` and `bytes` fields, it must be non-empty. - // 3. For repeated fields and maps, it must contain at least one element. - // - // Fields of other types are not supported by this option. - // - // For `oneof`s, the restrictions above do not apply. Any `oneof` group can be used - // without considering the field types, and its value will be checked directly without - // relying on the default values of the fields within the `oneof`. - // - // Example: defining two field groups. - // - // message PersonName { - // option (require).fields = "given_name | honorific_prefix & family_name"; - // - // string honorific_prefix = 1; - // string given_name = 2; - // string middle_name = 3; - // string family_name = 4; - // string honorific_suffix = 5; - // } - // - // In this example, at least `given_name` or a group of `honorific_prefix` - // and `family_name` fields must be set. - // - string fields = 1; - - // A user-defined error message. - // - // The specified message may include the following placeholders: - // - // 1. `${message.type}` – the fully qualified name of the validated message. - // 2. `${require.fields}` – the specified field groups. - // - // The placeholders will be replaced at runtime when the error is constructed. - // - string error_msg = 2; -} diff --git a/docs/content/docs/validation/developer/documentation/_index.md b/docs/content/docs/validation/developer/documentation/_index.md index c41dcdb7ac..a2476fb71a 100644 --- a/docs/content/docs/validation/developer/documentation/_index.md +++ b/docs/content/docs/validation/developer/documentation/_index.md @@ -34,7 +34,6 @@ Go-based code-embedding tool. The top-level layout is: | `_settings/` | Configuration for the code-embedding tool — see "[Embedded examples](embedded-examples.md)". | | `_script/` | Shell scripts that the Gradle tasks shell out to. | | `_bin/` | Prebuilt `embed-code-go` binaries for Linux, macOS, and Windows. | -| `_options/` | A copy of the Validation Protobuf options surface kept alongside the docs. | The underscore prefix marks directories that are *not* part of the Hugo site tree — Hugo ignores top-level paths starting with `_`. Everything Hugo From 8a7d53c125790061ad1c6215d23756bd59f74467 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 19:54:54 +0100 Subject: [PATCH 26/40] Correct the statement of the source pools for embedding --- .../developer/documentation/embedded-examples.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index 77ffb139ce..d6675ec8ac 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -11,9 +11,15 @@ them as plain Markdown. This keeps the snippets in lock-step with the code they document: when a method signature, a Protobuf option, or an example project file changes, the documentation either updates automatically (when `:docs:embedCode` runs) or fails CI (when `:docs:checkSamples` runs against -a stale page). The two source pools the documentation pulls from are the -Validation modules under the repository root and two Git submodules under -`docs/`. +a stale page). There are three source pools the documentation pulls from: + +1. The Validation library code itself — the repository root and the + production modules under it, exposed through the `root`, `runtime`, + `java`, and `context` source roots. +2. The Validation examples — the `docs/_examples/` Git submodule, exposed + through the `examples` source root. +3. The Spine Time library — the `docs/_time/` Git submodule, reached + through the `root` source root. ## Example sources From 53aa7797680104064558a1812183355725a46ba0 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 20:23:57 +0100 Subject: [PATCH 27/40] Fix the correctness of wording around update procedures Also: * Use n-dash as a workaround for https://github.com/SpineEventEngine/embed-code-go/issues/26. --- .../documentation/embedded-examples.md | 13 +++--- .../developer/documentation/procedures.md | 46 ++++++++++++------- .../developer/documentation/tooling.md | 4 +- 3 files changed, 38 insertions(+), 25 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index d6675ec8ac..46e1d955d4 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -122,19 +122,18 @@ manages. The tool replaces the *fenced code block* immediately following the element with the content extracted from the referenced source file between the `start` and `end` patterns. -```markdown - - -` ` `kotlin + +```kotlin val validationVersion by extra("2.0.0-SNAPSHOT.419") -` ` ` ``` +```` -(The fence is shown with spaces to keep this page renderable.) The four -relevant attributes are: +The four relevant attributes are: - `file` — `$source-root/relative/path/to/file.ext` where `source-root` is a name from `code-path`. diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index c76b524160..180d072102 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -75,8 +75,9 @@ and "[External tooling](tooling.md)". ## Refreshing embedded example sources from Spine Time The Spine Time library at `docs/_time/` is a Git submodule. Use these -steps when first cloning the repository or when intentionally moving the -submodule to a different commit. +steps when first cloning the repository, when refreshing the submodule to +its default remote branch, or when intentionally pinning it to a specific +commit. 1. Initialize and fetch the submodule on a fresh clone: @@ -84,8 +85,21 @@ submodule to a different commit. git submodule update --init --recursive docs/_time ``` -2. To move `_time/` to a specific commit, fetch and check it out inside - the submodule: +2. To refresh `_time/` to its default remote branch and re-embed snippets + from that revision, run: + + ```bash + ./gradlew :docs:embedCode + ./gradlew :docs:checkSamples + ``` + + The `:docs:embedCode` task runs + `git submodule update --remote --merge --recursive` before invoking the + embedding tool, so this path intentionally accepts the latest remote + revision selected by the submodule configuration. + +3. To pin `_time/` to a specific commit instead, fetch and check it out + inside the submodule: ```bash cd docs/_time @@ -94,26 +108,26 @@ submodule to a different commit. cd - ``` -3. Re-embed snippets that pull from the submodule and verify: +4. Re-embed snippets without running `:docs:embedCode`, because that task + would move the submodule back to the default remote branch before + embedding: ```bash - ./gradlew :docs:embedCode + ./gradlew :docs:updatePluginVersions + cd docs/_bin + ./embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed" + cd - ./gradlew :docs:checkSamples ``` -4. Commit the updated submodule pointer: +5. Commit the updated submodule pointer and any snippets changed by the + embedding step: ```bash - git add docs/_time + git add docs/_time docs/content/docs git commit -m "Update Spine Time submodule -> " ``` -Note that `:docs:embedCode` itself runs -`git submodule update --remote --merge --recursive` as part of its -script. The manual checkout in step 2 is what *pins* the submodule to a -specific revision; the automatic update tracks the submodule's default -remote branch. - ## Adding a new embedded code example 1. If the source file lives outside the existing source roots in @@ -125,11 +139,11 @@ remote branch. by an empty fenced code block. For example: ```markdown - - + ``` The `start` and `end` attributes are regular expressions matched diff --git a/docs/content/docs/validation/developer/documentation/tooling.md b/docs/content/docs/validation/developer/documentation/tooling.md index c5398517f3..90be11e87b 100644 --- a/docs/content/docs/validation/developer/documentation/tooling.md +++ b/docs/content/docs/validation/developer/documentation/tooling.md @@ -127,8 +127,8 @@ expects. ## What's next - "[Procedures](procedures.md)" — the recipes for updating `site-commons` - and `embed-code-go`, and for installing or upgrading the local Hugo and - Node toolchain. + and `embed-code-go`, plus the local build and preview commands that use + the Hugo and Node toolchain described above. [site-commons]: https://github.com/SpineEventEngine/site-commons [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates From fd4bedace6d7982fc1140f94b019268a6b80553b Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 20:27:20 +0100 Subject: [PATCH 28/40] Update dependency reports --- dependencies.md | 60 ++++++++++++++++++++++++------------------------- pom.xml | 2 +- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/dependencies.md b/dependencies.md index 089847728b..1599844c1f 100644 --- a/dependencies.md +++ b/dependencies.md @@ -1,6 +1,6 @@ -# Dependencies of `io.spine.tools:validation-context:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-context:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -1090,14 +1090,14 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:49 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-context-tests:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-context-tests:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -1791,28 +1791,28 @@ This report was generated on **Fri May 08 20:07:49 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-docs:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-docs:2.0.0-SNAPSHOT.416` ## Runtime ## Compile, tests, and tooling The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu May 07 21:35:57 WEST 2026** using +This report was generated on **Thu May 07 19:54:38 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-gradle-plugin:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-gradle-plugin:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -2864,14 +2864,14 @@ This report was generated on **Thu May 07 21:35:57 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:49 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-java:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-java:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -3961,14 +3961,14 @@ This report was generated on **Fri May 08 20:07:49 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:49 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-java-bundle:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-java-bundle:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : org.jetbrains. **Name** : annotations. **Version** : 13.0. @@ -4015,14 +4015,14 @@ This report was generated on **Fri May 08 20:07:49 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:46 WEST 2026** using +This report was generated on **Mon May 11 20:25:27 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-validation-jvm-runtime:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine:spine-validation-jvm-runtime:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -4822,14 +4822,14 @@ This report was generated on **Fri May 08 20:07:46 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:49 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-consumer:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-consumer:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -5511,14 +5511,14 @@ This report was generated on **Fri May 08 20:07:49 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-consumer-dependency:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-consumer-dependency:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -5976,14 +5976,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-extensions:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-extensions:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -6602,14 +6602,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-runtime:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-runtime:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -7170,14 +7170,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-validating:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-validating:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -7781,14 +7781,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-validator:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-validator:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.20.0. @@ -8526,14 +8526,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:48 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-validator-dependency:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-validator-dependency:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -8766,14 +8766,14 @@ This report was generated on **Fri May 08 20:07:48 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:47 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine.tools:validation-vanilla:2.0.0-SNAPSHOT.418` +# Dependencies of `io.spine.tools:validation-vanilla:2.0.0-SNAPSHOT.419` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -9116,6 +9116,6 @@ This report was generated on **Fri May 08 20:07:47 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri May 08 20:07:47 WEST 2026** using +This report was generated on **Mon May 11 20:25:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/pom.xml b/pom.xml index 47985d6de3..a4ae4397ce 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject. --> io.spine.tools validation -2.0.0-SNAPSHOT.418 +2.0.0-SNAPSHOT.419 2015 From f9b33ba1edd7f7e709160cd39504941df57e624c Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 20:45:50 +0100 Subject: [PATCH 29/40] Add reference to full `embed-code-go` syntax reference --- .../documentation/embedded-examples.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index 46e1d955d4..fbb365f7b0 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -122,6 +122,11 @@ manages. The tool replaces the *fenced code block* immediately following the element with the content extracted from the referenced source file between the `start` and `end` patterns. +This page describes the syntax used in the Validation documentation. +For the complete `embed-code-go` syntax — including named fragments, +multi-piece fragments, omitted boundaries, and the exact line-pattern +rules — see the upstream [embedding guide][embed-code-go-embedding]. + ````markdown Date: Mon, 11 May 2026 21:09:56 +0100 Subject: [PATCH 30/40] Add `docs` root for embedding --- docs/_settings/embed-code.yml | 2 ++ .../documentation/embedded-examples.md | 24 +++++++++++++------ 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/_settings/embed-code.yml b/docs/_settings/embed-code.yml index 38fd9a97c6..e94dc75e72 100644 --- a/docs/_settings/embed-code.yml +++ b/docs/_settings/embed-code.yml @@ -9,6 +9,8 @@ code-path: path: "../../java" - name: "context" path: "../../context" + - name: "docs" + path: ".." docs-path: "../content/docs/" code-includes: - ".gitignore" diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index fbb365f7b0..dc66c5c59a 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -11,7 +11,7 @@ them as plain Markdown. This keeps the snippets in lock-step with the code they document: when a method signature, a Protobuf option, or an example project file changes, the documentation either updates automatically (when `:docs:embedCode` runs) or fails CI (when `:docs:checkSamples` runs against -a stale page). There are three source pools the documentation pulls from: +a stale page). There are four source pools the documentation pulls from: 1. The Validation library code itself — the repository root and the production modules under it, exposed through the `root`, `runtime`, @@ -20,6 +20,8 @@ a stale page). There are three source pools the documentation pulls from: through the `examples` source root. 3. The Spine Time library — the `docs/_time/` Git submodule, reached through the `root` source root. +4. The documentation tree — the `docs/` directory, exposed through the + `docs` source root. ## Example sources @@ -60,10 +62,15 @@ The configuration file [`docs/_settings/embed-code.yml`][embed-code-yml] declares the source roots the embedding tool understands, where the documentation pages live, and which files are considered embeddable. + + ```yaml code-path: - name: "root" path: "../.." + - name: "docs" + path: ".." - name: "examples" path: "../_examples" - name: "runtime" @@ -92,6 +99,7 @@ binary). A page references a source root by its name, prefixed with `$`. | Name | Path | What it exposes | |------------|---------------------|--------------------------------------------------------------------------| | `root` | `../..` | The Validation repository root — top-level files (`version.gradle.kts`, `build.gradle.kts`, …) and any module not separately mapped. | +| `docs` | `..` | The `docs/` directory — documentation settings, scripts, and other documentation-local files. | | `examples` | `../_examples` | The Hello Validation example projects (the submodule above). | | `runtime` | `../../jvm-runtime` | The `:jvm-runtime` module — runtime library sources used in "[Runtime library](../runtime-library.md)". | | `java` | `../../java` | The `:java` module — Java code-generation sources used in "[Java code generation](../java-code-generation.md)". | @@ -119,10 +127,12 @@ to this list. An `` element marks a region in a Markdown page that the tool manages. The tool replaces the *fenced code block* immediately following -the element with the content extracted from the referenced source file -between the `start` and `end` patterns. +the element with the content extracted from the referenced source file. +When the element has `start` and `end` attributes, the tool embeds only +the lines between the matching patterns. When it has only `file`, the +tool embeds the whole file. -This page describes the syntax used in the Validation documentation. +This page describes the syntax used in the Validation documentation. For the complete `embed-code-go` syntax — including named fragments, multi-piece fragments, omitted boundaries, and the exact line-pattern rules — see the upstream [embedding guide][embed-code-go-embedding]. @@ -138,13 +148,13 @@ val validationVersion by extra("2.0.0-SNAPSHOT.419") ``` ```` -The four relevant attributes are: +The attributes used most often in Validation pages are: - `file` — `$source-root/relative/path/to/file.ext` where `source-root` is a name from `code-path`. -- `start` — an extended glob-style pattern matched against a single line. +- `start` — an extended glob-style pattern matched against a single line. The matching line is the *first* line included. -- `end` — an extended glob-style pattern matched against a single line. +- `end` — an extended glob-style pattern matched against a single line. The matching line is the *last* line included. To include a single line, use the same pattern for both. - The language tag on the fenced block (`kotlin`, `java`, `proto`, …) From f6cc2afba60e995db9a178fd9751fab327ba4ba9 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 21:14:44 +0100 Subject: [PATCH 31/40] Add `time` root for embedding --- docs/_settings/embed-code.yml | 2 ++ .../documentation/embedded-examples.md | 23 ++++++++++--------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/_settings/embed-code.yml b/docs/_settings/embed-code.yml index e94dc75e72..5d7e00574a 100644 --- a/docs/_settings/embed-code.yml +++ b/docs/_settings/embed-code.yml @@ -9,6 +9,8 @@ code-path: path: "../../java" - name: "context" path: "../../context" + - name: "time" + path: "../_time" - name: "docs" path: ".." docs-path: "../content/docs/" diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index dc66c5c59a..81462da6dd 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -18,8 +18,8 @@ a stale page). There are four source pools the documentation pulls from: `java`, and `context` source roots. 2. The Validation examples — the `docs/_examples/` Git submodule, exposed through the `examples` source root. -3. The Spine Time library — the `docs/_time/` Git submodule, reached - through the `root` source root. +3. The Spine Time library — the `docs/_time/` Git submodule, exposed + through the `time` source root. 4. The documentation tree — the `docs/` directory, exposed through the `docs` source root. @@ -53,8 +53,8 @@ extension points the documentation describes. To embed snippets from Spine Time's actual source — not a copy that would inevitably drift — the library is included as the `docs/_time/` Git submodule pointing at [`SpineEventEngine/time`][spine-time]. The -code-embedding tool then reads snippets straight from the submodule -working tree. +code-embedding tool then reads snippets from that working tree through +the `$time` source root. ## The `_settings/embed-code.yml` file @@ -69,8 +69,6 @@ documentation pages live, and which files are considered embeddable. code-path: - name: "root" path: "../.." - - name: "docs" - path: ".." - name: "examples" path: "../_examples" - name: "runtime" @@ -79,6 +77,10 @@ code-path: path: "../../java" - name: "context" path: "../../context" + - name: "time" + path: "../_time" + - name: "docs" + path: ".." docs-path: "../content/docs/" code-includes: - ".gitignore" @@ -99,16 +101,15 @@ binary). A page references a source root by its name, prefixed with `$`. | Name | Path | What it exposes | |------------|---------------------|--------------------------------------------------------------------------| | `root` | `../..` | The Validation repository root — top-level files (`version.gradle.kts`, `build.gradle.kts`, …) and any module not separately mapped. | -| `docs` | `..` | The `docs/` directory — documentation settings, scripts, and other documentation-local files. | | `examples` | `../_examples` | The Hello Validation example projects (the submodule above). | | `runtime` | `../../jvm-runtime` | The `:jvm-runtime` module — runtime library sources used in "[Runtime library](../runtime-library.md)". | | `java` | `../../java` | The `:java` module — Java code-generation sources used in "[Java code generation](../java-code-generation.md)". | | `context` | `../../context` | The `:context` module — the custom-validation context sources. | +| `time` | `../_time` | The Spine Time submodule used as the implementation example for custom validation. | +| `docs` | `..` | The `docs/` directory — documentation settings, scripts, and other documentation-local files. | -To embed from Spine Time, use the `$root` source root with a -`docs/_time/...` path. There is no dedicated source root for `_time/` -because everything in that submodule is reachable through the repository -root. +To embed from Spine Time, use the `$time` source root with a path relative +to `docs/_time/`. ### Pages directory (`docs-path`) From d6f9e4110a47395abfbce0a5be9f2d6515500d36 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 21:18:08 +0100 Subject: [PATCH 32/40] Remove task documents --- .../describe-documentation-plan-draft.md | 52 --- .agents/tasks/describe-documentation-plan.md | 321 ------------------ 2 files changed, 373 deletions(-) delete mode 100644 .agents/tasks/describe-documentation-plan-draft.md delete mode 100644 .agents/tasks/describe-documentation-plan.md diff --git a/.agents/tasks/describe-documentation-plan-draft.md b/.agents/tasks/describe-documentation-plan-draft.md deleted file mode 100644 index a921e71c25..0000000000 --- a/.agents/tasks/describe-documentation-plan-draft.md +++ /dev/null @@ -1,52 +0,0 @@ -# Task: Describe the technical details of the documentation process - -## Goal -- Create a comprehensive documentation that describes the technical details of the documentation - process for the Spine Validation library. - -## Content that we know needs to be there -- Description of the `docs` module and its purpose. -- Brief explanation that we use Hugo, the `_preview` directory and how the `docs` module - is going to be used when building the documentation section of the spine.io website. -- Explanation of the build tasks defined in `docs/build.gradle.kts` and their purposes. - Use `docs/GRADLE.md` as a reference or even text source for this section. -- Explanation of the paths used in the scripts and how to work with them. -- Description of how the example sources are included in the documentation project. -- Explanation of using Spine Time as an implementaiton example and that the library is added as GitModule because of this. -- Documentation of `settings/embed-code.yml` file and source roots under it. - -## Procedures to be documented - -The sections below describe what procedures should be documented. -This is not an exhaustive list, but it includes the most important ones that are known at the moment. - -### Incrementing the version of Validation -1. Update the version in `version.gradle.kts` file. -2. Run `./gradlew :docs:updatePluginVersions` to update the version of Validation Graldle plugin - in the examples and files documentation. -3. Commit the change to `version.gradle.kts` file using the commit message - ```text - Bump version -> `` - ``` -4. Commit the change to the remaining files using the commit message - ```text - Bump Validation -> `` - ``` -5. Run `./gradlew clean build` and commit `pom.xml` and `dependencies.md` using the commit - message `Update dependency reports` as usually when incrementing the version in - Spine SDK projects. - -### Updating the version of the CoreJvm Compiler -1. Update the version in the dependency object `CoreJvmCompiler` under `buildSrc`. -2. Run `./gradlew :docs:updatePluginVersions` to update the version of CoreJvm Graldle plugin - in the examples and files documentation. - -## Tasks that are known to be done -- [ ] Add `docs/README.md` file with the brief description, and the link to - the page under the `content` directory that explains the documentation process in more detail. - Remove `GRADLE.md` file as no longer needed after that. - -## Placement of the documentation in the navigation -- The documentation about the documentation process should be placed in the `content` - directory under `docs/validation/developer/documentation.md` file. -- It should be the last item in the `Developer` section of the documentation. diff --git a/.agents/tasks/describe-documentation-plan.md b/.agents/tasks/describe-documentation-plan.md deleted file mode 100644 index ecce2c8032..0000000000 --- a/.agents/tasks/describe-documentation-plan.md +++ /dev/null @@ -1,321 +0,0 @@ -# Plan: Describe the technical details of the documentation process - -This plan elaborates the brief in -[`describe-documentation-plan-draft.md`](describe-documentation-plan-draft.md). -The goal is to deliver a dedicated documentation sub-tree under the existing -Developer guide that explains, end to end, how the Spine Validation -documentation is authored, built, previewed, and released. - -## 1. Outcome - -A new sub-tree appears as the last item of the "Validation developer guide" -section of the documentation and answers the following questions: - -- What is the `docs` module and how does it fit into the `spine.io` website - build? -- How is the documentation built locally and previewed? -- Which Gradle tasks are involved, what do they do, and where do their outputs - land? -- How are source code examples embedded into the documentation, and why is - Spine Time wired in as a Git submodule? -- How is `settings/embed-code.yml` structured, and what are the source roots? -- How do contributors perform the recurring documentation-related procedures - (version bumps, tool updates, submodule refresh, adding pages, adding - embedded examples)? - -In addition, `docs/README.md` is introduced as the in-repo entry point, and -`docs/GRADLE.md` is retired because its content is folded into the new pages. - -## 2. Deliverables - -### 2.1 New documentation sub-tree - -Location: -`docs/content/docs/validation/developer/documentation/` - -Pages: - -- `_index.md` — Overview. Purpose of the `docs` module; relationship to Hugo - and the `_preview` directory; how the module participates in the `spine.io` - website build; reading map for the child pages. -- `build-tasks.md` — Gradle build tasks defined in `docs/build.gradle.kts`, - what each task does, dependencies between them, and the paths the scripts - rely on. Folds in the content of `docs/GRADLE.md`. Covers `:docs:runSite` - (local Hugo preview) and the task that produces the publishable output. -- `embedded-examples.md` — How example sources are included in the - documentation; the role of Spine Time as the implementation-example library - and the rationale for wiring it as a Git submodule under `_time`; structure - of `settings/embed-code.yml` and its source roots. -- `tooling.md` — External tooling the docs build depends on: - - `site-commons` (Go module) — what it provides, why it is a Go module, how - it is consumed. - - `embed-code-go` — what it does, how it is consumed by the docs build. -- `procedures.md` — Step-by-step recipes for recurring tasks (see section 3). - -### 2.2 In-repo entry point and cleanup - -- Add `docs/README.md` with a brief description of the `docs` module and a - link to the new overview page (`developer/documentation/_index.md`). -- Remove `docs/GRADLE.md` once its content has been migrated into - `developer/documentation/build-tasks.md`. Verify there are no remaining - references to `GRADLE.md` before deletion. - -### 2.3 Navigation update - -- Update `docs/data/docs/validation/2-0-0-snapshot/sidenav.yml`: add a nested - entry as the last item under the `developer` key. Use `file_path` values - relative to the version `content_path` (`docs/validation`), without the - `.md` suffix, and treating `_index.md` as the directory path. Preserve the - file's existing ordering, indentation, quoting style, and comments. - -Proposed entry (final wording to be confirmed when drafting): - -```yaml -- page: Documentation process - key: documentation - children: - - page: Overview - file_path: developer/documentation - - page: Build tasks - file_path: developer/documentation/build-tasks - - page: Embedded examples - file_path: developer/documentation/embedded-examples - - page: External tooling - file_path: developer/documentation/tooling - - page: Procedures - file_path: developer/documentation/procedures -``` - -## 3. Procedures to document on `procedures.md` - -Each procedure is presented as numbered steps with the exact commands, the -files touched, and the expected outcome. - -1. **Incrementing the version of Validation** — as drafted in the brief - (update `version.gradle.kts`, run `:docs:updatePluginVersions`, commit - sequence, run `clean build`, commit `pom.xml` and `dependencies.md` as - `Update dependency reports`). -2. **Updating the version of the CoreJvm Compiler** — update the - `CoreJvmCompiler` dependency object under `buildSrc`, run - `:docs:updatePluginVersions`. -3. **Refreshing the embedded example sources from Spine Time** — initial - submodule init/update for `_time`, switching to a specific commit, and how - the change propagates through the embed-code pipeline. -4. **Adding a new embedded code example** — declare or extend a source root - in `settings/embed-code.yml`, reference the snippet from a Markdown page, - verify it renders in preview. -5. **Adding or updating a documentation page** — create the Markdown file - under `content/docs/validation/...`, update the corresponding - `sidenav.yml` entry, preview locally, validate links. -6. **Updating `site-commons`** — bump the Go module version in `go.mod`, - tidy/vendor as required, verify the preview still renders correctly. -7. **Updating `embed-code-go`** — bump the tool version, re-run the embed - pipeline, verify embedded snippets. -8. **Building the documentation locally** — which Gradle task produces the - publishable output, where the output lands, and how it is consumed by the - `spine.io` website build. -9. **Previewing the documentation locally** — `:docs:runSite`, prerequisites, - how to reach the preview, troubleshooting tips. - -## 4. Cross-cutting content notes - -- Use fenced code blocks for every shell command and file path. Format file - and directory names as inline code. -- Follow `.agents/documentation-guidelines.md` for quotation style, footnote - links for external `https://` URLs, and widow/runt/orphan/river handling. -- Match identifiers (Gradle task names, Kotlin/Go module names, YAML keys) to - what is in the repository at the time of writing. -- Prefer concrete, executable steps and short paragraphs over abstract - description. - -## 5. Research items to verify before writing - -These must be confirmed against the current repo state during drafting: - -- Exact set and names of Gradle tasks defined in `docs/build.gradle.kts` - (including `:docs:runSite`, `:docs:updatePluginVersions`, and the build - task that produces the publishable output) and their inter-task - dependencies. -- Output directory of the documentation build and how/where the `spine.io` - website pipeline consumes it. -- Current contents and source-root structure of - `docs/_settings/embed-code.yml`. -- The exact role of the `_preview` directory in the local Hugo preview flow - (input/output, generated vs. checked-in). -- How `_time` is wired as a Git submodule (path, default branch/commit - policy) and which Gradle tasks consume it. -- Whether `site-commons` is consumed via `go.mod` directly under `docs/`, - via a Hugo module config, or both. -- Current means of pinning the `embed-code-go` version used by the build. -- The version selector for the documentation site (the `2-0-0-snapshot` - versus `2-0-x` entries in `docs/data/versions.yml`) to confirm the - sub-tree is added to the main version only. - -## 6. Work breakdown - -Ordered for incremental review: - -1. **Discovery pass.** Walk the repo and answer every research item in - section 5. Capture findings as notes (not committed) to feed the drafts. -2. **Skeleton commit.** Create empty `_index.md`, `build-tasks.md`, - `embedded-examples.md`, `tooling.md`, `procedures.md` with frontmatter - and section headings only. Update `sidenav.yml` with the new entry. - Verify the navigation renders via `:docs:runSite`. -3. **Draft `_index.md`** (overview) and `build-tasks.md` (migrate - `GRADLE.md` content; expand with task descriptions, paths, and outputs). -4. **Draft `embedded-examples.md`** (Spine Time submodule rationale, - `embed-code.yml` structure, page-side syntax for embedding snippets). -5. **Draft `tooling.md`** (`site-commons`, `embed-code-go`: purpose, - consumption, update mechanics — pure description here; the update steps - live in `procedures.md`). -6. **Draft `procedures.md`** covering all nine procedures with verified - commands and expected outcomes. -7. **Add `docs/README.md`** pointing to `_index.md`; remove `docs/GRADLE.md` - after confirming no remaining references. -8. **Validation pass.** - - `./gradlew :docs:runSite` and click through every new page; verify - navigation, code blocks, embedded snippets, and internal links. - - Run `./gradlew dokka` if any Kotlin/Java source comments were touched. - - Re-read each page for adherence to the documentation guidelines - (quotation rules, reference-style external links, no widows/runts). - -## 7. Discovery findings - -Captured 2026-05-11 from the current `master`-tracking working tree. Use as -the factual basis for drafting; re-verify if the repo state changes. - -### 7.1 Gradle tasks defined in `docs/build.gradle.kts` - -All tasks are registered on the `:docs` project. Inter-task dependencies in -parentheses. - -| Task | Type | Purpose | -|-------------------------------|--------|------------------------------------------------------------------------------------------------| -| `updateValidationPluginVersion` | `UpdatePluginVersion` | Rewrites `id("io.spine.validation") version "…"` in every `build.gradle.kts` under `_examples/` to `validationVersion` from `version.gradle.kts`. Also updates `kotlin("…") version "…"` to `Kotlin.version`. | -| `updateCoreJvmPluginVersion` | `UpdatePluginVersion` | Same mechanism for `io.spine.core-jvm`, using `CoreJvmCompiler.version` from `buildSrc`. | -| `updatePluginVersions` | aggregate | Depends on the two tasks above. | -| `installDependencies` | `Exec` | Runs `_script/install-dependencies` → `npm install` inside `_preview/`. Not meant to be run manually. | -| `runSite` | `Exec` | Runs `_script/hugo-serve` → `hugo server` inside `_preview/`. Local preview. Depends on `installDependencies`. | -| `buildSite` | `Exec` | Runs `_script/hugo-build` → `hugo` inside `_preview/`. Builds the static site. Depends on `installDependencies`. | -| `embedCode` | `Exec` | Runs `_script/embed-code` (does `git submodule update --remote --merge --recursive`, then `_bin/embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed"`). Depends on `updatePluginVersions`. Manual use. | -| `checkSamples` | `Exec` | Runs `_script/check-samples` (uses `embed-code-linux` under GitHub Actions, `embed-code-macos` locally; `-mode="check"`). Depends on `updatePluginVersions`. Executed by `.github/workflows/check-code-embedding.yml`. | -| `publishAllToMavenLocal` | aggregate | Depends on every `PublishToMavenLocal` task across the root project's allprojects. | -| `buildExamples` | `RunGradle` | Runs `buildAll` inside `_examples/`. Depends on `publishAllToMavenLocal` and `updatePluginVersions`. | -| `buildAll` | aggregate | Depends on `publishAllToMavenLocal` and `buildExamples`. Used by `.github/workflows/check-code-embedding.yml`. | - -The `UpdatePluginVersion` task type is defined at -`buildSrc/src/main/kotlin/io/spine/gradle/docs/UpdatePluginVersion.kt`. - -### 7.2 Build output and `spine.io` handoff - -- `buildSite` writes Hugo output to `docs/_preview/public/` (Hugo's default - for the `_preview` working directory). -- `docs/GRADLE.md` states that the preview site is **not** meant to be - published as-is. The content of the `docs` module is merged into the main - documentation project at https://github.com/SpineEventEngine/documentation - for publication on `spine.io`. -- There is no workflow in `.github/workflows/` that deploys the preview - output. CI only exercises `:docs:buildAll` and `:docs:checkSamples` - (see `.github/workflows/check-code-embedding.yml`). - -### 7.3 `_preview` directory role - -- `_preview` is the Hugo project root for local preview. -- `_preview/hugo.toml` imports two Hugo modules: - - `../..` — the `docs/` module itself (provides `content/`, `data/`, - `layouts/`). - - `github.com/SpineEventEngine/site-commons` — the shared site theme/layout. -- `_preview/go.mod` pins both `site-commons` (currently - `v0.0.0-20260507130158-84db050dfe11`) and - `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`. -- `_preview/package.json` declares Node devDependencies (`postcss`, - `autoprefixer`, `@fullhuman/postcss-purgecss`, etc.) installed by - `npm install` via `installDependencies`. -- `_preview/public/` holds the generated static site (`docs/`, `index.html`, - `css`/`js`/`img` assets, sitemap, etc.). Re-created on every `buildSite` - or `runSite`. - -### 7.4 Git submodules - -`.gitmodules` (repo root): - -- `config` → `https://github.com/SpineEventEngine/config` -- `docs/_examples` → `https://github.com/spine-examples/hello-validation` -- `docs/_time` → `https://github.com/SpineEventEngine/time` - -Notes: - -- `_examples` contains the Hello Validation example projects - (`first-model`, `first-model-with-framework`, `external`). The settings - file there is the canonical list; the `includeBuild` referenced by - `docs/GRADLE.md` lives in `_examples/settings.gradle.kts`, not in - `docs/`. -- `_time` is the Spine Time library, used as the *implementation example* - for custom validation. The `_script/embed-code` runs - `git submodule update --remote --merge --recursive`, so the submodules - track their default remote branches when running the embed pipeline. - -### 7.5 `embed-code-go` pinning - -- The tool is consumed as **checked-in prebuilt binaries** under - `docs/_bin/`: - - `embed-code-linux`, `embed-code-macos`, `embed-code-windows.exe`. -- There is no version pin in source form in this repo. The - `_script/check-samples` selects the Linux binary on GitHub Actions - (`GITHUB_ACTIONS=true`) and the macOS binary locally. The Windows binary - is present but currently not selected by either script. -- `_script/embed-code` hard-codes the `embed-code-macos` binary path. -- "Updating `embed-code-go`" therefore means rebuilding the binaries from - https://github.com/SpineEventEngine/embed-code-go and replacing the - artifacts under `docs/_bin/`. - -### 7.6 `settings/embed-code.yml` - -Current contents declare five `code-path` source roots: - -| Name | Path | What it exposes | -|-----------|---------------------|----------------------------------------------------------------| -| `root` | `../..` | The Validation repo root (top-level files, all modules). | -| `examples`| `../_examples` | The Hello Validation example projects (Git submodule). | -| `runtime` | `../../jvm-runtime` | The `jvm-runtime` module. | -| `java` | `../../java` | The Java code-generation module. | -| `context` | `../../context` | The custom-validation context module. | - -Plus: - -- `docs-path: "../content/docs/"` — root of pages that can host embedded - snippets. -- `code-includes` — file globs the tool considers as embeddable sources: - `.gitignore`, `**/*.kts`, `**/*.md`, `**/*.proto`, `**/*.java`, - `**/*.kt`, `**/*.yml`. - -### 7.7 Documentation versions and sidenav target - -- `docs/data/versions.yml` declares two `validation` entries: - `2-0-0-snapshot` (`is_main: true`) and `2-0-x` (not main, both - `switcher` flags false). -- `docs/data/docs/validation/` contains a `sidenav.yml` only for - `2-0-0-snapshot/`. There is no `2-0-x/` sub-directory. The new sub-tree - must be added to - `docs/data/docs/validation/2-0-0-snapshot/sidenav.yml` only. - -### 7.8 Other observations relevant to the docs - -- `docs/_options/options.proto` is a copy of the Protobuf options surface - used by the documentation embeds. Not strictly part of the new doc's - scope but worth a brief mention in `_index.md` or `embedded-examples.md`. -- The version bump procedure in the draft references "the version in - `version.gradle.kts`" — confirmed at the repo root - (`val validationVersion by extra("2.0.0-SNAPSHOT.419")`). -- The custom Gradle task plumbing (`UpdatePluginVersion`, - `io.spine.gradle.RunGradle`) is shared across the SDK; this repo - consumes them from the local `buildSrc`. - -## 8. Out of scope - -- Changes to historical doc versions (`2-0-x` and earlier) or their - `sidenav.yml` files. -- Documenting unrelated developer procedures not part of the documentation - pipeline. -- Restructuring the existing Developer guide pages beyond appending the new - sub-tree. From 95d25ed8ad243a06815e68d0a5bb2ed8b7bd1b31 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 21:21:00 +0100 Subject: [PATCH 33/40] Remove Claude memory --- .../memory/MEMORY.md | 3 --- ...ack_do_not_replicate_upstream_tool_docs.md | 24 ------------------ .../feedback_repo_name_links_backticked.md | 25 ------------------- .../memory/feedback_spine_io_no_backticks.md | 19 -------------- 4 files changed, 71 deletions(-) delete mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md delete mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md delete mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md delete mode 100644 .claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md deleted file mode 100644 index 5e02c3b45c..0000000000 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/MEMORY.md +++ /dev/null @@ -1,3 +0,0 @@ -- [Do not use backticks around "spine.io"](feedback_spine_io_no_backticks.md) — render spine.io as plain prose or a link, never as code. -- [Do not replicate upstream tool documentation](feedback_do_not_replicate_upstream_tool_docs.md) — link to upstream READMEs for external tools; don't restate build/release recipes in this repo. -- [Backtick repo/tool names when used as link text to their repo](feedback_repo_name_links_backticked.md) — render `site-commons`, `embed-code-go`, etc. as inline code when they are the visible text of a link to the project's repository. diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md deleted file mode 100644 index ee70675465..0000000000 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_do_not_replicate_upstream_tool_docs.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: Do not replicate upstream tool documentation in Validation docs -description: When the Validation docs touch an external tool (embed-code-go, site-commons, …), point at the upstream README — don't restate build/test/release recipes. -type: feedback ---- - -When the Validation documentation describes an external tool — for example -`embed-code-go` or `site-commons` — link to the upstream README for build, -test, and release details. Do not restate those instructions in this repo's -docs. - -**Why:** Upstream is the source of truth and changes independently. Copying -its recipes here creates drift the moment upstream changes its build -command, Go version requirement, or output paths. The user specifically -called this out after I had inlined the full `embed-code-go` cross-compile -sequence into "Procedures" — they pointed out that the Validation build does -not compile `embed-code-go`, so a fetch-and-drop recipe is the only thing -this repo should document. - -**How to apply:** For each external tool, write what *this* repository does -with it (where binaries land, which file pins the version, which Gradle -task consumes it) and link to the upstream README/section for everything -else. Default to "fetch the prebuilt artifact" over "build from source" -when the upstream publishes binaries. diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md deleted file mode 100644 index e45d4d1323..0000000000 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_repo_name_links_backticked.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: Backtick tool/repo names when used as link text to their repository -description: In Validation docs, render repo/tool identifiers (site-commons, embed-code-go, …) as inline code when they appear as link text pointing to their repository. -type: feedback ---- - -When a repo or tool identifier — for example `site-commons`, `embed-code-go`, -or a similar slug — appears as Markdown link text whose target is the -project's repository, format the link text as inline code: - -- Yes: `[`site-commons`][site-commons]` -- No: `[site-commons][site-commons]` - -**Why:** These are identifiers (repo names, package names, executable -names), so the documentation guidelines' rule of "format file and directory -names as code" extends naturally. Reviewers explicitly asked for this after -I had left such link text unformatted. - -**How to apply:** When you introduce a new link to one of these -repositories — or to any similarly named tool — wrap the visible link text -in backticks. Contrast with brand/site names like spine.io (see -"Do not use backticks around spine.io"), which stay plain prose. - -In tables and other places where the same name appears outside a link, the -existing rule still applies: format identifiers as inline code. diff --git a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md b/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md deleted file mode 100644 index 73df127e59..0000000000 --- a/.claude/projects/-Users-sanders-Projects-Spine-validation/memory/feedback_spine_io_no_backticks.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: Do not use backticks around "spine.io" -description: When writing docs in this repo, write spine.io as plain prose (or as a link), never wrapped in backticks. -type: feedback ---- - -Do not put backticks around `spine.io` — write it as plain prose or, where -appropriate, as a Markdown link to https://spine.io. The user removed -backticks I had added in `_index.md` and `build-tasks.md` and explicitly -asked me not to use them. - -**Why:** "spine.io" is a brand/site name in this project, not code or a -file/directory identifier. The repo's documentation-guidelines say to format -file and directory names as code; brand names are not in that bucket. - -**How to apply:** In all docs and prose under this repo, render "spine.io" -as `spine.io` (no backticks) or as `[spine.io](https://spine.io)`. The same -default likely applies to other brand/site names — keep them plain unless -they unambiguously refer to a file or identifier. From ee40227a495202b3bbe622d821397f9410ca7b23 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 21:28:22 +0100 Subject: [PATCH 34/40] Describe pushing examples in procedures --- .../developer/documentation/procedures.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index 180d072102..cd8dae3d42 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -41,18 +41,24 @@ and "[External tooling](tooling.md)". ```text Bump Validation -> `` ``` +5. Push the changes to the `hello-validation` repository, + which the `docs/_examples/` submodule points to: -5. Run a clean build and refresh the dependency reports: + ```bash + cd docs/_examples + git push + cd - + ``` + +6. Run a clean build and refresh the dependency reports: ```bash ./gradlew clean build ``` Then commit the regenerated `pom.xml` and `dependencies.md` with: - - ```text - Update dependency reports - ``` + `Update dependency reports` message. + This step follows the same convention used elsewhere in the Spine SDK projects. From ce96127a82296f68928f2281a4ad30992e61822d Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 11 May 2026 21:50:28 +0100 Subject: [PATCH 35/40] Remove redundant (c) header --- docs/_script/embed-code | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/docs/_script/embed-code b/docs/_script/embed-code index fdaf56a789..e68bb9d3ba 100755 --- a/docs/_script/embed-code +++ b/docs/_script/embed-code @@ -1,29 +1,4 @@ #!/usr/bin/env bash -# -# Copyright 2020, TeamDev. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Redistribution and use in source and/or binary forms, with or without -# modification, must retain the above copyright notice and the following -# disclaimer. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -# # Load environment variables for the case of execution from the Gradle build if they exist. BASH_PROFILE=~/.bash_profile From 277900fd224fb59fe53b8789e27177c71fe868a3 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 May 2026 16:09:41 +0100 Subject: [PATCH 36/40] Improve wording on inlining examples --- .../validation/developer/documentation/embedded-examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/embedded-examples.md b/docs/content/docs/validation/developer/documentation/embedded-examples.md index 81462da6dd..e6671c378a 100644 --- a/docs/content/docs/validation/developer/documentation/embedded-examples.md +++ b/docs/content/docs/validation/developer/documentation/embedded-examples.md @@ -6,8 +6,8 @@ headline: Documentation # Embedded examples -The documentation embeds snippets from real source files instead of inlining -them as plain Markdown. This keeps the snippets in lock-step with the code +The documentation embeds snippets from real source files instead of copying their +content into Markdown files. This keeps the snippets in lock-step with the code they document: when a method signature, a Protobuf option, or an example project file changes, the documentation either updates automatically (when `:docs:embedCode` runs) or fails CI (when `:docs:checkSamples` runs against From dd4c5db9d04f97ee82d64ecf48806d4d7cd6caf0 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 May 2026 16:13:11 +0100 Subject: [PATCH 37/40] Add link to the versioning policy --- .../docs/validation/developer/documentation/procedures.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index cd8dae3d42..88b872a7d0 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -19,6 +19,8 @@ and "[External tooling](tooling.md)". ```kotlin val validationVersion by extra("") ``` + For the detailed instructions on selecting an increment, + see the [Versioning policy][versioning-policy] of the Spine SDK. 2. Propagate the new version into the example projects' plugin coordinates: @@ -313,3 +315,4 @@ for any build, test, or release questions. [theme-updates]: https://github.com/SpineEventEngine/site-commons#theme-updates [embed-code-go]: https://github.com/SpineEventEngine/embed-code-go [embed-code-bin]: https://github.com/SpineEventEngine/embed-code-go/tree/master/bin +[versioning-policy]: https://github.com/SpineEventEngine/documentation/wiki/Versioning From 67981d1f6960fce2940f0a18bc45546177f0daa0 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 May 2026 16:14:44 +0100 Subject: [PATCH 38/40] Update build time --- dependencies.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/dependencies.md b/dependencies.md index 1599844c1f..035c68aeed 100644 --- a/dependencies.md +++ b/dependencies.md @@ -1090,7 +1090,7 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -1791,7 +1791,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -2864,7 +2864,7 @@ This report was generated on **Thu May 07 19:54:38 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -3961,7 +3961,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -4015,7 +4015,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:27 WEST 2026** using +This report was generated on **Tue May 12 16:13:28 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -4822,7 +4822,7 @@ This report was generated on **Mon May 11 20:25:27 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -5511,7 +5511,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -5976,7 +5976,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -6602,7 +6602,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -7170,7 +7170,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -7781,7 +7781,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -8526,7 +8526,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:31 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -8766,7 +8766,7 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:30 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). @@ -9116,6 +9116,6 @@ This report was generated on **Mon May 11 20:25:28 WEST 2026** using The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Mon May 11 20:25:28 WEST 2026** using +This report was generated on **Tue May 12 16:13:30 WEST 2026** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file From c1d59287fc738aaca54ed54e76ebc7df6bcaf6e2 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 May 2026 16:15:05 +0100 Subject: [PATCH 39/40] Fix the wording around server restart --- .../docs/validation/developer/documentation/procedures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/validation/developer/documentation/procedures.md b/docs/content/docs/validation/developer/documentation/procedures.md index 88b872a7d0..03d73ad86c 100644 --- a/docs/content/docs/validation/developer/documentation/procedures.md +++ b/docs/content/docs/validation/developer/documentation/procedures.md @@ -297,7 +297,7 @@ for any build, test, or release questions. 3. Edits to Markdown files under `docs/content/` hot-reload automatically. Edits to `docs/data/` files (including `sidenav.yml`) - and to Hugo layouts require a restart of the task. + and to Hugo layouts require a restart of the server. 4. To stop the server, press `Ctrl+C` in the terminal running the task. From e841b610e5138bb8e5dcd27d55c75c9151c7b5e0 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 May 2026 16:33:38 +0100 Subject: [PATCH 40/40] Use typographic quotes --- .../docs/validation/developer/documentation/build-tasks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/validation/developer/documentation/build-tasks.md b/docs/content/docs/validation/developer/documentation/build-tasks.md index 85cb9a4d76..5d93c17d4e 100644 --- a/docs/content/docs/validation/developer/documentation/build-tasks.md +++ b/docs/content/docs/validation/developer/documentation/build-tasks.md @@ -47,8 +47,8 @@ this task, so it is rarely invoked manually. Runs `_script/hugo-serve` → `hugo server` from `_preview/`. The Hugo dev server hot-reloads pages on edits to `docs/content/`. This is the standard -way to preview documentation changes locally; see the "Previewing the -documentation locally" recipe in "[Procedures](procedures.md)". +way to preview documentation changes locally; see the “Previewing the +documentation locally” recipe in "[Procedures](procedures.md)". ### `buildSite`