Add content to the "Concepts" section of the documentation#272
Add content to the "Concepts" section of the documentation#272alexander-yevsyukov merged 46 commits intomasterfrom
Conversation
Agents pick up the file repeatedly. We will describe time options when we describe custom validation.
Also: * Improve the file name.
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive content to the "Concepts" section of the Spine Validation documentation, providing a conceptual explanation of how validation works at build time and runtime. The changes introduce new documentation pages explaining validation options, constraints, violations, and error handling, along with supporting skill definitions for documentation writing.
Changes:
- Created the main Concepts landing page explaining validation vocabulary, constraint execution, and nested validation
- Added an Options overview page detailing where validation options come from and how they influence generated code
- Introduced documentation writing skill definitions and templates to guide future documentation efforts
- Removed obsolete
time_options.protofile and updated documentation planning files
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
docs/content/docs/validation/02-concepts/_index.md |
Replaces draft placeholder with comprehensive concepts overview |
docs/content/docs/validation/02-concepts/options-overview.md |
New page explaining validation options and code generation pipeline |
docs/data/docs/validation/2-0-0-snapshot/sidenav.yml |
Adds Options overview to navigation structure |
.agents/tasks/validation-documentation-plan.md |
Updates documentation plan to reflect completed Concepts section |
.agents/tasks/archive/concepts-plan.md |
Archives completed concepts implementation plan |
.agents/tasks/working-with-error-messages.md |
Defines requirements for future error message documentation |
skills/writer/SKILL.md |
Defines documentation writing skill for the validation repository |
skills/writer/assets/templates/*.md |
Provides templates for KDoc examples and documentation pages |
docs/_options/time_options.proto |
Removes file (likely moved or consolidated elsewhere) |
docs/_examples |
Updates subproject reference |
version.gradle.kts |
Increments snapshot version |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Get theme updates with the fixed image rendering
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 24 out of 25 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `field_value` — the invalid value packed as `google.protobuf.Any`. | ||
|
|
||
| When you need a human-readable message, format the `TemplateString` from the violation. | ||
| See [Working with error messages](working-with-error-messages.md) for message formatting, |
There was a problem hiding this comment.
There are two concrete link issues: (1) ../01-getting-started/first-model is inconsistent with the later first-model.md link and is likely to break depending on the site’s URL strategy; align them (prefer the same target used elsewhere in this page). (2) working-with-error-messages.md does not match the added page filename (error-messages.md), so those links will 404—update both occurrences to error-messages.md.
| - Customize and format messages: | ||
| [Working with error messages](working-with-error-messages.md). |
There was a problem hiding this comment.
There are two concrete link issues: (1) ../01-getting-started/first-model is inconsistent with the later first-model.md link and is likely to break depending on the site’s URL strategy; align them (prefer the same target used elsewhere in this page). (2) working-with-error-messages.md does not match the added page filename (error-messages.md), so those links will 404—update both occurrences to error-messages.md.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 32 out of 33 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 32 out of 33 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,12 @@ | |||
| ```kotlin | |||
There was a problem hiding this comment.
This template’s outer fenced code block uses triple backticks, but it also contains a nested triple-backtick fence inside the KDoc example (line 6). That will prematurely close the outer fence in Markdown renderers. Use a different outer fence (e.g., quadruple backticks or tildes) so the nested ```kotlin block is preserved as literal text (the .agents/.../kdoc-example.md version already demonstrates the safer approach).
| A(Protobuf) --> B(Generated code) | ||
| B --> C(Domain logic) | ||
| subgraph B [Generated Java/Kotlin/TypeScript] |
There was a problem hiding this comment.
The Mermaid diagram defines node B (line 128) and then reuses B as a subgraph identifier (line 130), which can break rendering due to identifier collision. Also, the subgraph is empty (it doesn’t contain node B). Rename the subgraph to a distinct id and include the B node within the subgraph so the diagram renders consistently.
| A(Protobuf) --> B(Generated code) | |
| B --> C(Domain logic) | |
| subgraph B [Generated Java/Kotlin/TypeScript] | |
| A(Protobuf) --> B | |
| B --> C(Domain logic) | |
| subgraph GeneratedLayer [Generated Java/Kotlin/TypeScript] | |
| B(Generated code) |
| description: Write, edit, and restructure user-facing and developer-facing documentation for the Spine `validation` repository. Use when asked to create/update docs such as `README.md`, `docs/**`, `CONTRIBUTING.md`, and other Markdown documentation; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples. | ||
| --- | ||
|
|
||
| # Write documentation (repo-specific) | ||
|
|
||
| ## Decide the target and audience | ||
|
|
||
| - Identify the target reader: end user, contributor, maintainer, or tooling/automation. | ||
| - Identify the task type: new doc, update, restructure, or documentation audit. | ||
| - Identify the acceptance criteria: “what is correct when the reader is done?” | ||
|
|
||
| ## Choose where the content should live | ||
|
|
||
| - Prefer updating an existing doc over creating a new one. | ||
| - Place content in the most discoverable location: | ||
| - `README.md`: project entry point and “what is this?”. | ||
| - `docs/`: longer-form docs (follow existing conventions in that tree). | ||
| - `CONTRIBUTING.md`: contributor workflows. | ||
| - Source KDoc: API usage, examples, and semantics that belong with the code. | ||
|
|
||
| ## Follow local documentation conventions | ||
|
|
||
| - Follow `.agents/documentation-guidelines.md` and `.agents/documentation-tasks.md`. | ||
| - Use fenced code blocks for commands and examples; format file/dir names as code. | ||
| - Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed. | ||
|
|
||
| ## Make docs actionable | ||
|
|
||
| - Prefer steps the reader can execute (commands + expected outcome). | ||
| - Prefer concrete examples over abstract descriptions. | ||
| - Include prerequisites (versions, OS, environment) when they are easy to miss. | ||
| - Use consistent terminology (match code identifiers and existing docs). | ||
|
|
||
| ## KDoc-specific guidance | ||
|
|
||
| - For public/internal APIs, include at least one example snippet demonstrating common usage. | ||
| - When converting from Javadoc/inline comments to KDoc: | ||
| - Remove HTML like `<p>` and preserve meaning. | ||
| - Prefer short paragraphs and blank lines over HTML formatting. | ||
|
|
||
| ## Validate changes | ||
|
|
||
| - For code changes, follow `.agents/running-builds.md`. | ||
| - For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`. | ||
|
|
There was a problem hiding this comment.
The PR adds the Writer skill in two locations (skills/writer/... and .agents/skills/writer/...) with seemingly duplicated content (SKILL.md, openai.yaml, templates). This duplication is likely to drift over time. Consider keeping a single canonical location (preferably .agents/skills/writer/... based on the PR description) and removing or explicitly documenting why both copies must exist and how they are kept in sync.
| description: Write, edit, and restructure user-facing and developer-facing documentation for the Spine `validation` repository. Use when asked to create/update docs such as `README.md`, `docs/**`, `CONTRIBUTING.md`, and other Markdown documentation; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples. | |
| --- | |
| # Write documentation (repo-specific) | |
| ## Decide the target and audience | |
| - Identify the target reader: end user, contributor, maintainer, or tooling/automation. | |
| - Identify the task type: new doc, update, restructure, or documentation audit. | |
| - Identify the acceptance criteria: “what is correct when the reader is done?” | |
| ## Choose where the content should live | |
| - Prefer updating an existing doc over creating a new one. | |
| - Place content in the most discoverable location: | |
| - `README.md`: project entry point and “what is this?”. | |
| - `docs/`: longer-form docs (follow existing conventions in that tree). | |
| - `CONTRIBUTING.md`: contributor workflows. | |
| - Source KDoc: API usage, examples, and semantics that belong with the code. | |
| ## Follow local documentation conventions | |
| - Follow `.agents/documentation-guidelines.md` and `.agents/documentation-tasks.md`. | |
| - Use fenced code blocks for commands and examples; format file/dir names as code. | |
| - Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed. | |
| ## Make docs actionable | |
| - Prefer steps the reader can execute (commands + expected outcome). | |
| - Prefer concrete examples over abstract descriptions. | |
| - Include prerequisites (versions, OS, environment) when they are easy to miss. | |
| - Use consistent terminology (match code identifiers and existing docs). | |
| ## KDoc-specific guidance | |
| - For public/internal APIs, include at least one example snippet demonstrating common usage. | |
| - When converting from Javadoc/inline comments to KDoc: | |
| - Remove HTML like `<p>` and preserve meaning. | |
| - Prefer short paragraphs and blank lines over HTML formatting. | |
| ## Validate changes | |
| - For code changes, follow `.agents/running-builds.md`. | |
| - For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`. | |
| description: Compatibility alias for the writer skill. The canonical definition lives in `.agents/skills/writer/SKILL.md`; do not update this copy directly. | |
| --- | |
| # Writer skill (alias) | |
| This file exists only for backward compatibility with tooling that expects skills | |
| under `skills/`. The canonical, up-to-date definition of the **writer** skill, | |
| including its detailed guidance, templates, and configuration, is located at: | |
| - `.agents/skills/writer/SKILL.md` | |
| When modifying the writer skill: | |
| - Edit `.agents/skills/writer/SKILL.md` instead of this file. | |
| - If this file must change (for example, renaming the skill ID), mirror only the | |
| minimal metadata in the front matter and keep this notice intact. | |
| No further guidance is intentionally included here to avoid divergence from the | |
| canonical definition. |
| ## Placement | ||
|
|
||
| - Placement of the page: after “Built-in options”, before “Custom validation”. | ||
| - Hugo section (minimal change): add the page under `docs/content/docs/validation/02-concepts/`. |
There was a problem hiding this comment.
This task plan says the third-party messages page should live under 02-concepts/third-party-messages.md, but the PR actually introduces docs/content/docs/validation/04-third-party-messages/_index.md and wires it in the sidenav as 04-third-party-messages. Update the plan to match the implemented location (or adjust the docs location) so future work doesn’t target the wrong path.
|
|
||
| ## Output | ||
|
|
||
| Implemented as `docs/content/docs/validation/02-concepts/third-party-messages.md`. |
There was a problem hiding this comment.
This task plan says the third-party messages page should live under 02-concepts/third-party-messages.md, but the PR actually introduces docs/content/docs/validation/04-third-party-messages/_index.md and wires it in the sidenav as 04-third-party-messages. Update the plan to match the implemented location (or adjust the docs location) so future work doesn’t target the wrong path.
alexander-yevsyukov
requested review from
armiol
and removed request for
Copilot
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 32 out of 33 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 28 out of 29 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This PR adds the content to the "Concepts" section and adds empty pages drafting the navigation structure for the complete documentation.
Other notable changes
.agentsdirectory.