awesome-copilot/skills/github-release/references/semver-rules.md

SemVer Decision Rules

Reference: https://semver.org/

---

Version format

vMAJOR.MINOR.PATCH

• MAJOR — incompatible API changes
• MINOR — new backward-compatible functionality
• PATCH — backward-compatible bug fixes

Pre-1.0 note: if the current version is 0.x.y, anything goes — MINOR bumps are common for breaking changes. Once past 1.0.0, the rules below apply strictly.

---

What counts as a MAJOR bump (breaking change)

Breaking changes are any modifications that could cause a consumer of the library to experience a compile error, runtime error, or behavior change without changing their own code.

Examples:

• Removing a public function, class, method, or constant
• Renaming a public function, class, method, or constant
• Changing a function signature (adding required parameters, removing parameters, changing parameter types, changing return type)
• Changing observable behavior that callers depend on (e.g., error types thrown, event names emitted, return value shape)
• Changing a required configuration key or its accepted values
• Dropping support for a runtime/language version that was previously supported
• Removing or renaming a publicly exported module path

When in doubt, prefer a MAJOR bump over a MINOR. It's better to signal a breaking change than to silently break consumers.

---

What counts as a MINOR bump (new feature)

• Adding a new public function, class, method, or constant
• Adding optional parameters to an existing function (with backward-compatible defaults)
• Implementing a new protocol/interface that doesn't affect existing ones
• Adding new configuration keys with sensible defaults
• Deprecating (but not removing) a public API — removal comes in a future MAJOR

---

What counts as a PATCH bump

• Fixing a bug where behavior was incorrect relative to documented intent
• Improving performance without changing the public API
• Internal refactoring with no external observable difference
• Documentation updates
• Dependency updates that don't change the library's own public surface
• CI/CD, test, tooling changes
• Security fixes that don't break the API

---

Multiple changes — precedence

When a release contains a mix of change types, the highest precedence wins:

MAJOR > MINOR > PATCH

One breaking change + ten new features = MAJOR bump.

---

First release (no prior tags)

Default to 1.0.0 regardless of what's in the diff. Inform the user.

---

Edge cases

Situation	Recommendation
Only internal/private symbols changed	PATCH
Type annotation added to previously untyped function	PATCH (non-breaking)
Changing default value of optional parameter	Treat as MAJOR if callers might rely on old default
Adding a new required config option to an optional block	MINOR if the block itself is optional, otherwise MAJOR
Reverting a previous commit entirely	Follow what the net diff shows, not the revert message