You've seen the PR description that says "fixes stuff." You've seen the commit history that reads like a ransom note. You've been the one trying to figure out if v1.6.0 or v2.0.0 is correct at 10pm before a deploy. Tired of inconsistent commit messages? Wish your AI coding assistant could help enforce semver and conventional commits?
Free, copy-paste-ready rule files for Cursor, GitHub Copilot, Claude Code, and Windsurf. They enforce semantic versioning best practices, conventional commits, and proper git tagging. No setup drama. Drop them in, restart your editor, done.
A Quick Primer: What Is Semantic Versioning?
If you're new to semantic versioning (SemVer), here's the basics:
Version numbers follow MAJOR.MINOR.PATCH:
v2.3.1
│ │ └─ PATCH: Bug fixes (backward compatible)
│ └─── MINOR: New features (backward compatible)
└───── MAJOR: Breaking changes (NOT backward compatible)
Examples:
- v1.5.3 → v1.5.4: You fixed a bug. PATCH bump.
- v1.5.4 → v1.6.0: You added a new feature. MINOR bump.
- v1.6.0 → v2.0.0: You removed an API or changed behavior. MAJOR bump.
Consumers (humans and tools) can tell at a glance whether an upgrade is safe. v1.6.0 from v1.5.4? Probably fine. v2.0.0? I need to read the migration guide.
Why Enforcing Semver Matters
1. Breaking Changes That Aren't Flagged
A "fix" that changes an API signature breaks consumers. If you tag it as PATCH (v1.5.4), downstream projects assume they can upgrade safely. They can't. Enforcing semver means breaking changes get MAJOR bumps and clear migration paths.
2. Customer and User Trust
When your changelog says "v1.2.0 – bug fixes and improvements," customers expect no breaking changes. If you shipped one and didn't bump MAJOR, you've eroded trust. Consistent semver builds it.
3. Dependency Management
Tools like npm, cargo, and go mod use semver for compatibility. If your package doesn't follow it, you break the ecosystem. Enforcing it in your commits and tags keeps everything predictable.
Get release management tips in your inbox
Practical guides on release notes, changelogs, and shipping better software. No spam, unsubscribe anytime.
Conventional Commits and Semver
Conventional Commits map commit messages to version bumps:
| Commit Type | Version Impact | Example |
|---|---|---|
feat: | MINOR ↑ | v1.5.3 → v1.6.0 |
fix: | PATCH ↑ | v1.5.3 → v1.5.4 |
feat!: or BREAKING CHANGE: | MAJOR ↑ | v1.5.3 → 2.0.0 |
docs:, chore:, etc. | No bump | v1.5.3 → v1.5.3 |
Format:
<type>[optional scope]: <description>
[optional body]
[optional footer]
Examples:
feat(auth): add OAuth2 authentication
fix(api): handle null values in user response
feat!: refactor auth API
BREAKING CHANGE: login() now returns Promise<User>
Once your commits follow this convention, tools like semantic-release and ReleaseRay can generate versions and release notes automatically.
Cursor Rule File (Copy-Paste Ready)
Place this in .cursor/rules/80-versioning.mdc:
---
description: Enforce semantic versioning and conventional commits
globs: "**/*"
alwaysApply: true
---
# Semantic Versioning & Conventional Commits
## Commit Format (REQUIRED)
<type>[scope]: <description>
Types: feat, fix, feat!, fix!, docs, style, refactor, perf, test, chore, ci, build
- feat: → MINOR bump
- fix: or perf: → PATCH bump
- feat!: or BREAKING CHANGE: → MAJOR bump
## Examples
feat(auth): add OAuth2
fix(api): resolve null pointer
feat!: change API signature
BREAKING CHANGE: getUser() now returns Promise
## Git Tags
Always: git tag -a v1.2.3 -m "Release v1.2.3: Brief summary"
Never: git tag v1.2.3 (lightweight, no metadata)
## Version Bump Rules
MAJOR: Breaking changes
MINOR: New features
PATCH: Bug fixes
Restart Cursor, and your AI assistant will enforce these rules when suggesting commit messages and tags.
Full Rule Files for All Assistants
For complete, production-ready rule files with more examples, edge cases, and tool-specific instructions:
Download all rule files from our downloads page →
| Assistant | File | Install Path |
|---|---|---|
| Cursor | cursor-rules.mdc | .cursor/rules/80-versioning.mdc |
| GitHub Copilot | copilot-instructions.md | .github/copilot-instructions.md or personal instructions |
| Claude Code | claude-code-rules.mdc | .claude/versioning-rules.mdc |
| Windsurf | windsurf-rules.mdc | .windsurf/versioning-rules.mdc |
All files are free, customizable, and include conventional commits enforcement, semver decision trees, and git tagging guidance.
How This Pairs With Automated Release Notes
Once your commits follow a convention and your versions are semantic, ReleaseRay can generate meaningful release notes automatically. Define a release range, analyze commits, generate persona-specific notes, publish to GitHub, Intercom, changelog, Slack. Garbage in, garbage out. These rules ensure quality input for quality output.
Installation Quick Reference
Cursor
curl -O https://releaseray.com/downloads/cursor-rules.mdc
mkdir -p .cursor/rules
mv cursor-rules.mdc .cursor/rules/80-versioning.mdc
# Restart Cursor
GitHub Copilot
curl -O https://releaseray.com/downloads/copilot-instructions.md
mkdir -p .github
mv copilot-instructions.md .github/copilot-instructions.md
git add .github/copilot-instructions.md
git commit -m "docs: add Copilot instructions"
Claude Code
curl -O https://releaseray.com/downloads/claude-code-rules.mdc
mkdir -p .claude
mv claude-code-rules.mdc .claude/versioning-rules.mdc
Windsurf
curl -O https://releaseray.com/downloads/windsurf-rules.mdc
mkdir -p .windsurf
mv windsurf-rules.mdc .windsurf/versioning-rules.mdc
Beyond Rules: Git Hooks and CI
For stricter enforcement:
- Husky + commitlint: Reject commits that don't match conventional format
- semantic-release: Auto-bump versions and create tags on merge to main
See our Automate Branch Promotions post for GitHub Actions workflows that preserve semantic versioning through squash merges.
Key Takeaways
Semantic versioning (MAJOR.MINOR.PATCH) builds trust and enables tooling. Conventional commits (feat, fix, BREAKING CHANGE) map cleanly to version bumps. AI assistant rules make enforcement effortless; your assistant suggests the right format. Automated release notes depend on quality commits and tags. Garbage in, garbage out. Download all rule files for Cursor, Copilot, Claude Code, and Windsurf: releaseray.com/docs/downloads
Related Posts
- Automate Branch Promotions with GitHub Actions
- Why Multi-Persona Release Notes Matter
- Getting Started with ReleaseRay
Written by Cristobal Mitchell, founder of ReleaseRay. We build tools that make release workflows effortless.
Enjoyed this post?
Practical guides on release notes, changelogs, and shipping better software. No spam, unsubscribe anytime.
Cristobal Mitchell
Founder of ReleaseRay
Building ReleaseRay — automated release notes from GitHub PRs for developers, PMs, and customers.
Related Posts
How to Automate Your Changelog with GitHub Actions (Step-by-Step)
A practical comparison of four approaches to automated changelog generation: Release Drafter, Changesets, Conventional Commits tooling, and ReleaseRay. Includes working GitHub Actions YAML, honest tradeoffs, and a recommendation for every team size.
Release Notes Best Practices: The Complete Guide for Engineering Teams (2026)
How to write release notes that actually get read. Audience awareness, formatting standards, and automation without the team burnout. The definitive guide for engineering teams.
Automate Branch Promotions with GitHub Actions
Free GitHub Actions templates to automate release workflows: auto-create staging and production PRs with semantic version prediction. Stop manual branch promotions and version bumping.
Ready to automate your release notes?