docs(release): add VERSIONING policy and PR versioning checklist

[nutt-adam]

Adds release/versioning guardrails to enforce version bump + changelog discipline per merged issue PR.\n\n## Included\n- New policy (SemVer, bump policy, tag policy, v0.3 trigger criteria)\n- New with required versioning checklist\n- README link to \n\nThis is process/docs only.

Summary by CodeRabbit

• Documentation
  • Added versioning and release policy documentation
  • Updated README with links to new documentation
  • Introduced pull request template for standardized contributor workflows

[coderabbitai]

📝 Walkthrough

Walkthrough

A new versioning and release infrastructure is established through three complementary additions: a GitHub PR template for standardized version management, detailed versioning documentation, and a README reference to the versioning policy.

Changes

Cohort / File(s)	Summary
Versioning and Release Infrastructure .github/pull_request_template.md, VERSIONING.md, README.md	Added a structured PR template guiding contributors through versioning, validation, and release steps. Introduced comprehensive VERSIONING.md documenting SemVer usage, version bump policies (PATCH/MINOR/MAJOR), tagging procedures, and v0.3.0 trigger conditions. Updated README with a documentation link to the versioning policy.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 From fuzzy burrow deep below,
I've sewn the seeds of version flow—
With tags and bumps and templates neat,
Our releases now skip to beat! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding VERSIONING policy and PR versioning checklist documentation for release management.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch auto/issue-29-20260316181157

📝 Coding Plan

• Generate coding plan for human review comments

---

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.}

Tip

You can disable poems in the walkthrough.

Disable the reviews.poem setting to disable the poems in the walkthrough.

[coderabbitai]

🧹 Nitpick comments (3)

VERSIONING.md (1)

52-71: Consider adding commit verification to the tagging example.

The tagging policy is clear, but the bash example could be more defensive about ensuring the tag references the correct merge commit.

📋 Optional refinement to add verification step

 git checkout main
 git pull --ff-only
+# verify you're on the expected merge commit:
+git log -1 --oneline
 
 git tag v0.2.4
 git push origin v0.2.4

This helps catch scenarios where main has moved since the PR merge or multiple PRs were merged between tagging operations.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@VERSIONING.md` around lines 52 - 71, Update the bash example to verify the
tag points at the expected merge commit by adding a step to resolve and confirm
the merge commit for origin/main (e.g., use git fetch origin --tags and capture
origin/main's commit hash) and compare it to the commit you intend to tag before
running git tag vX.Y.Z and git push; ensure the example references origin/main
and the tag format vX.Y.Z and shows an explicit check that the tag target equals
the merge commit SHA to prevent tagging an unintended commit.

.github/pull_request_template.md (2)

16-24: Clarify package version vs tag version format (X.Y.Z vs vX.Y.Z).

Line 16 suggests a v-prefixed version, but Line 6 refers to Cargo.toml (typically bare SemVer like 0.2.3). Recommend separating fields to avoid accidental mismatch between crate version and git tag.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/pull_request_template.md around lines 16 - 24, The template mixes a
v-prefixed tag and bare crate version which can cause mismatches; update the
lines around "Version selected: `v`__________" and the validation checklist to
separate crate version and git tag explicitly (e.g., add two fields like "Crate
version: X.Y.Z" and "Git tag: vX.Y.Z") and adjust the Release checklist to
require the git tag field and confirm Cargo.toml matches the Crate version;
locate and change the "Version selected: `v`__________" string and any
references to "Tag planned/applied (`vX.Y.Z`)" and "Cargo.toml" to ensure both
versions are captured and validated independently.

---

5-10: Make version-bump checks explicitly conditional to avoid contradictory “required” signals.

As written, Line 6 and Line 7 read as required for every PR, while Line 9 allows no-bump PRs. Consider splitting this into mutually exclusive paths (“behavioral change” vs “docs/chore/no behavior change”) so authors don’t have to guess which boxes to leave unchecked.

Proposed template tweak

 ## Versioning (required)
-- [ ] I updated `Cargo.toml` version
-- [ ] I added/updated `CHANGELOG.md`
-- [ ] I documented release impact in this PR
-- [ ] If no bump, I explicitly justify why this is docs/chore/no behavior change
+- [ ] This PR changes behavior/contracts and I updated `Cargo.toml` version
+- [ ] This PR changes behavior/contracts and I added/updated `CHANGELOG.md`
+- [ ] I documented release impact in this PR
+- [ ] This PR is docs/chore/no behavior change; no version bump is required, and justification is included

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/pull_request_template.md around lines 5 - 10, Change the "##
Versioning (required)" checklist into two mutually exclusive subsections so
contributors clearly choose one path: add a subsection header like "If bumping
version / behavioral change" containing the checkboxes for `Cargo.toml` and
`CHANGELOG.md`, and a separate subsection "If no version bump (docs/chore/no
behavior change)" with the explicit justification checkbox; update the wording
to indicate authors must pick one path (e.g., "Select the applicable path and
complete its checkboxes") and ensure the original required marker only applies
to selecting a path, not both sets of checks.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/pull_request_template.md:
- Around line 16-24: The template mixes a v-prefixed tag and bare crate version
which can cause mismatches; update the lines around "Version selected:
`v`__________" and the validation checklist to separate crate version and git
tag explicitly (e.g., add two fields like "Crate version: X.Y.Z" and "Git tag:
vX.Y.Z") and adjust the Release checklist to require the git tag field and
confirm Cargo.toml matches the Crate version; locate and change the "Version
selected: `v`__________" string and any references to "Tag planned/applied
(`vX.Y.Z`)" and "Cargo.toml" to ensure both versions are captured and validated
independently.
- Around line 5-10: Change the "## Versioning (required)" checklist into two
mutually exclusive subsections so contributors clearly choose one path: add a
subsection header like "If bumping version / behavioral change" containing the
checkboxes for `Cargo.toml` and `CHANGELOG.md`, and a separate subsection "If no
version bump (docs/chore/no behavior change)" with the explicit justification
checkbox; update the wording to indicate authors must pick one path (e.g.,
"Select the applicable path and complete its checkboxes") and ensure the
original required marker only applies to selecting a path, not both sets of
checks.

In `@VERSIONING.md`:
- Around line 52-71: Update the bash example to verify the tag points at the
expected merge commit by adding a step to resolve and confirm the merge commit
for origin/main (e.g., use git fetch origin --tags and capture origin/main's
commit hash) and compare it to the commit you intend to tag before running git
tag vX.Y.Z and git push; ensure the example references origin/main and the tag
format vX.Y.Z and shows an explicit check that the tag target equals the merge
commit SHA to prevent tagging an unintended commit.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9a60ca66-ce55-430d-9643-2be78cf20fcc

📥 Commits

Reviewing files that changed from the base of the PR and between 9b6502c and 83139c4.

📒 Files selected for processing (3)

• .github/pull_request_template.md
• README.md
• VERSIONING.md