Document plugin version file keys omit the v prefix

[matteotrubini]

The example on this page used v-prefixed keys ("v1.0.1"), which is the opposite of the convention: the v belongs to migration and seed directory names, and to the script paths referenced from the file — not to the keys.

This is not cosmetic. version_compare() orders v below any digit, so a file mixing prefixed and unprefixed keys rendered the changelog out of order — exactly the situation this page was leading authors into, since its example used a prefixed key on a plugin whose real keys are unprefixed.

Fixed on the core side by wintercms/winter#1560, which compares on the normalized version while preserving the keys as written.

The corrected examples now match create:plugin (modules/system/console/scaffold/plugin/version.stub) and the first-party plugins that architecture/maintainer-guide.md points to as reference files — both of which use unprefixed keys with v-prefixed script paths.

Keys keep their quotes: an unquoted 1.0 parses as a float and is truncated to 1 as a PHP array key. See the winter/sample fixture in the core repo, whose YAML deliberately produces non-string keys.

Also adds the note explaining the keys/directories distinction. The pre-existing note is preserved as the second paragraph of the same blockquote, following the convention used elsewhere in this repo.

Summary by CodeRabbit

• Documentation
  • Updated version examples to omit the v prefix from version keys while retaining it in migration and seed paths.
  • Clarified the distinction across regular, important, and migration/seed update examples.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 6d186652-c1d0-4346-a5fb-bc59cd29e7b8

📥 Commits

Reviewing files that changed from the base of the PR and between 363910b and 4527c1a.

📒 Files selected for processing (1)

• plugin/updates.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The update documentation changes version keys in its examples to omit the v prefix. It clarifies that migration and seed directory names and script paths retain the prefix.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to 4527c

The documentation clarifies the version-key and script-path conventions without changing runtime behavior; no actionable merge risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to 4527c

The change affects 1 system.

Changed systems: plugin

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — plugin (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in plugin/updates.md: The example version keys change from v1.x.x to 1.x.x; migration and seed script paths remain prefixed with v.
• observed — Modified behavior in plugin/updates.md: A note now distinguishes version keys, which omit v, from migration and seed directory names and script paths, which use it. The note also retains the guidance that version descriptions may contain multiple entries and script paths may appear in any position.
• observed — Modified behavior in plugin/updates.md: The single-comment example changes its version key from v1.0.1 to 1.0.1.
• observed — Modified behavior in plugin/updates.md: The important-update example changes its version key from v1.1.0 to 1.1.0.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main documentation change: plugin version-file keys omit the v prefix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}