Document Home Assistant Core versioning scheme

[agners]

Proposed change

Add a Versioning page describing the CalVer YYYY.MM.PATCH format used by Core, including beta, development, and nightly version suffixes, and link it from the Misc sidebar category.

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Editing or restructuring documentation guidelines
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request:

Summary by CodeRabbit

Documentation

• Added documentation describing Home Assistant Core's versioning scheme, including the CalVer format (YYYY.MM.PATCH), pre-release version types, and best practices for version comparisons.

[Copilot]

Pull request overview

Adds a new developer documentation page explaining Home Assistant Core’s CalVer-based versioning scheme and how pre-release/development/nightly suffixes work, then exposes that page in the Core documentation sidebar under “Misc”.

Changes:

• Added a new Versioning documentation page describing YYYY.MM.PATCH and PEP 440-compatible suffixes (bN, .devN, .devYYYYMMDDHHMM).
• Documented where the Core version is defined and how it is bumped via script/version_bump.py.
• Linked the new page from the Core → Misc sidebar section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
sidebars.js	Adds the new versioning doc to the Core “Misc” sidebar items so it’s discoverable.
docs/versioning.md	New page documenting Core version format, pre-release/development variants, and recommended comparison approach.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation explaining Home Assistant Core's CalVer versioning scheme and integrates it into the developer documentation sidebar. The new documentation covers version format, pre-release rules, code locations, version-bumping tools, and guidance for version comparison.

Changes

Versioning Documentation

Layer / File(s)	Summary
Versioning documentation and sidebar integration docs/versioning.md, sidebars.js	New documentation describes the YYYY.MM.PATCH CalVer format, PEP 440 pre-release/development versions, where the version is defined and how it is bumped, plus best practices for version comparison using AwesomeVersion. The sidebar's Misc category is updated to link to this new page.

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and directly summarizes the main change: adding documentation for Home Assistant Core's versioning scheme.
Description check	✅ Passed	The description follows the template structure with a clear proposed change, appropriate type of change selection, and includes the checklist section. The description adequately explains the purpose and scope of the documentation addition.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch document-core-version

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/versioning.md`:
- Around line 7-9: Update the fenced code block that currently contains
"YYYY.MM.PATCH" to include a language identifier for proper rendering and syntax
highlighting — add "text" after the opening backticks so the block becomes
```text ... ```; locate the block containing the literal "YYYY.MM.PATCH" and
modify only the opening fence to include the language.
- Line 38: Revise the instruction sentence to front the goal and use a direct
tone: replace the conditional phrasing "When you need to gate behavior on a Home
Assistant Core version, compare versions with AwesomeVersion..." with an
authoritative imperative such as "To gate behavior on a Home Assistant Core
version, use AwesomeVersion to compare versions rather than parsing the string
yourself," keeping the AwesomeVersion link and the note about correct handling
of pre-releases, development, and patch releases; update the sentence in
docs/versioning.md accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3a0ca88d-9066-4aae-964f-1997929710ff

📥 Commits

Reviewing files that changed from the base of the PR and between a712bfa and 338a2c9.

📒 Files selected for processing (2)

• docs/versioning.md
• sidebars.js