Contents

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”, “Embedded examples”, and “External tooling”.

Incrementing the version of Validation

Update the version literal in version.gradle.kts:
```
val validationVersion by extra("<new-version>")
```
For the detailed instructions on selecting an increment, see the Versioning policy of the Spine SDK.
Propagate the new version into the example projects’ plugin coordinates:
```
./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/.
Commit version.gradle.kts on its own with:
```
Bump version -> `<new-version>`
```
Commit the remaining files touched by step 2 with:
```
Bump Validation -> `<new-version>`
```
Push the changes to the hello-validation repository, which the docs/_examples/ submodule points to:
```
cd docs/_examples
git push
cd -
```
Run a clean build and refresh the dependency reports:
```
./gradlew clean build
```
Then commit the regenerated pom.xml and dependencies.md with: Update dependency reports message.
This step follows the same convention used elsewhere in the Spine SDK projects.

Updating the version of the CoreJvm Compiler

Update the version in the CoreJvmCompiler dependency object under buildSrc.
Propagate the new version into the example projects’ plugin coordinates:
```
./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, when refreshing the submodule to its default remote branch, or when intentionally pinning it to a specific commit.

Initialize and fetch the submodule on a fresh clone:

git submodule update --init --recursive docs/_time

To refresh _time/ to its default remote branch and re-embed snippets from that revision, run:
```
./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.
To pin _time/ to a specific commit instead, fetch and check it out inside the submodule:
```
cd docs/_time
git fetch origin
git checkout <commit-or-ref>
cd -
```

Re-embed snippets without running :docs:embedCode, because that task would move the submodule back to the default remote branch before embedding:

./gradlew :docs:updatePluginVersions
cd docs/_bin
./embed-code-macos -config-path="../_settings/embed-code.yml" -mode="embed"
cd -
./gradlew :docs:checkSamples

Commit the updated submodule pointer and any snippets changed by the embedding step:

git add docs/_time docs/content/docs
git commit -m "Update Spine Time submodule -> <commit-or-ref>"

Adding a new embedded code example

If the source file lives outside the existing source roots in _settings/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.
In the target Markdown page, write an <embed-code> element followed by an empty fenced code block. For example:
```
<embed—code
  file="$root/version.gradle.kts"
  start="val validationVersion"
  end="val validationVersion">
</embed—code>
```
The start and end attributes are regular expressions matched against single lines; the matching lines are included.
Embed and verify:
```
./gradlew :docs:embedCode
./gradlew :docs:checkSamples
```
The fenced block under the element is now populated with the snippet.
Preview the page locally (see “Previewing the documentation locally” below) and confirm the snippet renders with the right syntax highlighting.
Commit the page, the snippet contents, and any changes to _settings/embed-code.yml.

For the underlying mechanics, see “Embedded examples”.

Adding or updating a documentation page

Create or edit the Markdown file under docs/content/docs/validation/<section>/. Match the frontmatter convention used by the surrounding pages (title, description, headline: Documentation).
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.
Preview locally (see “Previewing the documentation locally”) and click through every internal link.
Follow the project documentation guidelines in documentation-guidelines.md — 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” in the site-commons README, wrapped with the verification steps used in this repository.

From docs/_preview/, pull the latest theme version:

cd docs/_preview
hugo mod get -u github.com/SpineEventEngine/site-commons
cd -

Preview the site and click through the navigation, code blocks, and embedded snippets:
```
./gradlew :docs:runSite
```

Commit and push the resulting changes to docs/_preview/go.mod and docs/_preview/go.sum:

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/. The authoritative copies are published by the upstream project under embed-code-go/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.

From embed-code-go/bin, download the three binaries on the branch or tag you want to ship: embed-code-linux, embed-code-macos, embed-code-windows.exe.
Replace the files of the same names under docs/_bin/.

Make sure the macOS and Linux binaries are executable:

chmod +x docs/_bin/embed-code-macos docs/_bin/embed-code-linux

Verify that the new binaries still produce the same embedded output the repository expects:
```
./gradlew :docs:checkSamples
```
If checkSamples reports drift caused by the tool itself (formatting, whitespace, …), run ./gradlew :docs:embedCode and inspect the diff before committing.
Commit the updated binaries under docs/_bin/ with a message that names the upstream commit they were pulled from.

Building the documentation locally

Build the site:
```
./gradlew :docs:buildSite
```
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.
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” for the relationship.

Previewing the documentation locally

Start the Hugo dev server:
```
./gradlew :docs:runSite
```
Open the URL printed by hugo server, typically http://localhost:1313/.
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 server.
To stop the server, press Ctrl+C in the terminal running the task.

What’s next

“Documentation process” — overview and how this section fits into the wider documentation pipeline.
“Build tasks” — reference for every Gradle task these recipes invoke.