Migrate the committers' wiki content into guidelines#15
Merged
alexander-yevsyukov merged 11 commits intoJun 12, 2026
Conversation
Map all 20 pages of the committers' wiki to their destinations in this repository, plan the migration phases, and record the deferred wiki-side back-link edits as a checklist to run after the content lands on master. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Add `guidelines/kotlin-code-style.md` and `guidelines/java-code-style.md` with the content of the corresponding committers' wiki pages, modernized: the dependency-objects package is now `io.spine.dependency`, and the non-compiling Kotlin snippet in the constants section is repaired. Link the new pages from `coding.md` and index them in `_TOC.md` (also fixing the duplicated item numbering there). The Protobuf page needed no work — `guidelines/protobuf.md` already supersedes it. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Add `guidelines/javadoc.md`, `guidelines/kdoc.md`, and `guidelines/todo-comments.md` with the content of the corresponding committers' wiki pages. `documentation.md` now points to the in-repo TODO-comments page instead of the wiki, gains the sentence-case headers rule from the wiki's "Documentation conventions" page, and links the new Javadoc/KDoc pages. The Dokka v1 build snippets of the wiki's KDoc page are superseded by `running-builds.md` and were not migrated; the defective grep regexes on the TODO page were repaired. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
- `version-policy.md` now carries the full Spine SDK versioning policy (snapshot, release, patch, and flavour versions), the "no snapshots under Gradle" rationale from the "Using Gradle" page, and a "Publishing" section — instead of delegating to the wiki. - `testing.md` gains the conventions of the wiki "Testing" page, deferring the details to the `kotlin-jvm-tester` skill. - New `git-workflow.md` absorbs the "Branching" and "Pull Requests" pages; new `packages-and-artifacts.md` and `module-to-repository.md` mirror their wiki counterparts. - `running-builds.md` gains the Gradle-wrapper rule; `project-structure-expectations.md` gains the shared `config` submodule section; `_TOC.md` indexes the new pages. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
The `bump-version` skill now resolves its `[version-policy]` reference to `guidelines/version-policy.md`; `kotlin-jvm-tester` no longer cites the wiki as the upstream of the testing conventions; the archived task doc names the wiki page without linking it. `CONTRIBUTING.md` pointed to the predecessor wiki (`SpineEventEngine.github.io/wiki`, now a stale one-page stub) for the style guides — it points to `guidelines/_TOC.md` now. Outside the migration ledger, no file in the repository references the wiki anymore. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Reconcile the merged version policy (scope the per-advancement PATCH mandate to 1.x lines; explain that SNAPSHOT.NUMBER versions are immutable releases, not Maven snapshots), drop the nested-class capitalization clause of testing.md that contradicted the kotlin-jvm-tester examples, repoint the stale wiki mention in the review-docs skill to `todo-comments.md`, convert inline external links in the new pages to reference style, shorten over-long Javadoc headings, even out the java-code-style TOC depth, and apply assorted wording fixes. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Align the breaking-change rounding rule of the version policy with the `bump-version` skill (next multiple of ten, not "next dozen"), reflow ten runt lines, scope the sentence-case rule to titles and headings, clarify the nested-test-class naming wording, and fix minor phrasing. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Round 3 approved the branch; apply its cosmetic nits: keep the "IntelliJ IDEA" product name unbroken across a line break, fix the article before "constructor documentation", and reflow three colon lead-in lines. The task ledger moves to in-review: the agents-side migration is complete, and only the deferred wiki-side checklist remains. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Contributor
There was a problem hiding this comment.
Pull request overview
Migrates Spine committers’ wiki guidance into this repository’s in-repo guidelines/ so agent and contributor standards are self-sufficient, and removes wiki references across skills and contributor docs (with deferred wiki back-links tracked in a task ledger).
Changes:
- Added new guideline pages for Kotlin/Java style, Javadoc/KDoc, TODO format, git workflow, packages/artifacts, and module extraction.
- Expanded existing guidelines (versioning, testing, documentation, running builds, project structure) to remove prior wiki delegation.
- Removed remaining wiki links from skills and
CONTRIBUTING.md, and introduced a migration ledger with a deferred wiki-side checklist.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/review-docs/SKILL.md | Updates TODO-comment guidance to point to the new in-repo TODO conventions page. |
| skills/kotlin-jvm-tester/SKILL.md | Removes upstream wiki reference now that conventions are in-repo. |
| skills/bump-version/SKILL.md | Repoints version-policy reference from wiki to in-repo guideline. |
| guidelines/version-policy.md | Replaces wiki delegation with the full versioning/publishing policy in-repo. |
| guidelines/todo-comments.md | Adds the canonical TODO comment format and related tooling tips. |
| guidelines/testing.md | Adds a conventions summary and points to kotlin-jvm-tester as the detailed authority. |
| guidelines/running-builds.md | Adds the Gradle wrapper requirement. |
| guidelines/project-structure-expectations.md | Documents the shared config submodule usage. |
| guidelines/packages-and-artifacts.md | Introduces dependency/package/artifact separation guidance. |
| guidelines/module-to-repository.md | Adds a step-by-step guide for extracting a module into a new repo. |
| guidelines/kotlin-code-style.md | Adds Kotlin style extensions beyond standard Kotlin conventions. |
| guidelines/kdoc.md | Adds KDoc rules and Dokka verification guidance. |
| guidelines/javadoc.md | Adds Javadoc conventions and Dokka-based verification guidance. |
| guidelines/java-code-style.md | Adds Java style rules (Google style + Spine-specific conventions). |
| guidelines/git-workflow.md | Adds branching + PR workflow conventions. |
| guidelines/documentation.md | Updates documentation rules to link to new Javadoc/KDoc/TODO pages and adds header casing guidance. |
| guidelines/coding.md | Updates core coding-guideline links to include Kotlin + Java code-style pages. |
| guidelines/_TOC.md | Rebuilds the guidelines index to include newly added pages and fixes numbering. |
| CONTRIBUTING.md | Replaces stale wiki home link with in-repo developer guidelines index. |
| .agents/tasks/wiki-content-migration.md | Adds the migration task ledger, decisions, and deferred wiki-side checklist. |
| .agents/tasks/archive/kotlin-jvm-tester-skill/kotlin-jvm-tester-skill.md | Updates archived task note to reflect that testing guidance has moved in-repo. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Make the ill-formed-TODO grep portable (`-E` with `[0-9]` instead of GNU-only `-P` with `\d`), and let the review-docs skill enforce the actual `TODO:yyyy-MM-dd:contributor:` prefix instead of the stale "owner/issue reference" wording. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 355f7caad4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Per the Codex review on PR #15: the unqualified "each feature must bump the minor component" could read as applying to day-to-day snapshot PRs, contradicting the SNAPSHOT.NUMBER flow and the bump-version skill. The rule now applies to releases explicitly. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Unify the version-policy wording on "repository root" (the wiki-era "subproject" read like a Gradle submodule), and make the TODO grep recipes deterministic: search "." with --exclude-dir=.git instead of "*", which skipped hidden paths and depended on the working directory. https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
armiol
approved these changes
Jun 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses #7 (agents-side phases; the wiki-side back-link step is deferred by design).
Context
Issue #7 calls for migrating the committers' wiki into this repository so that agent guidelines are self-sufficient and the wiki can eventually collapse into a single index page linking here. This PR performs the full agents-side migration; the wiki itself is deliberately untouched — the required wiki edits are recorded as a checklist in the task ledger.
What changed
New guideline pages (migrated from their wiki counterparts):
kotlin-code-style.md,java-code-style.md,javadoc.md,kdoc.md,todo-comments.md,git-workflow.md(Branching + Pull Requests),packages-and-artifacts.md,module-to-repository.md.Extended pages:
version-policy.mdnow carries the full versioning policy (snapshot/release/patch/flavor) plus a Publishing section instead of delegating to the wiki;testing.mdgains the conventions summary (deferring details tokotlin-jvm-tester);documentation.mdgains the sentence-case headers rule and in-repo TODO/Javadoc/KDoc pointers;running-builds.mdgains the Gradle-wrapper rule;project-structure-expectations.mdgains the sharedconfigsubmodule section;_TOC.mdindexes everything (and fixes its duplicated numbering).Wiki-link removal:
bump-versionandkotlin-jvm-testerskills, the archived task note, andCONTRIBUTING.md(which pointed at the stale predecessor wiki) no longer reference any wiki. Outside the task ledger,grep -r "documentation/wiki"finds nothing.Content modernized during migration (each decision logged in the ledger): the dependency-objects package is
io.spine.dependency; the breaking-change version rounding follows thebump-versionskill ("next multiple of ten", not the wiki's "next dozen"); the per-advancement PATCH mandate is scoped to 1.x lines; Javadoc verification goes throughdokkaGenerate; broken wiki snippets (non-compiling Kotlin example, defective grep regexes) were repaired; the wiki's "capitalize nested test-class names" detail was dropped as contradicting the owner-reviewedkotlin-jvm-testerexamples.Not migrated, owner decision requested (proposals in the ledger):
IntelliJ-IDEA-configuration(IDEA 14/15-era),Build-artifacts(Travis-era),Validating-Builders(v1.9 product doc), and the Groovy section ofUsing-Gradle(legacy; Kotlin DSL is the standard).Task ledger
.agents/tasks/wiki-content-migration.md— page-by-page disposition table, the deferred wiki-side checklist (back-links, final index page, archive proposals), decision log, and lifecycle note (the ledger stays alive after merge until the wiki phase completes and #7 closes).Verification
documentation/wikiorSpineEventEngine.github.io/wikireference outside the ledger.review-docsreview rounds: APPROVE WITH CHANGES → APPROVE WITH CHANGES → APPROVE; all findings fixed in dedicated commits.https://claude.ai/code/session_01A55GUjnC5u48GSjVMKeCeJ
Generated by Claude Code