Semantic Versioning and Gem Constraints

Direct Answer

Semantic Versioning uses MAJOR.MINOR.PATCH to describe changes to a declared public API: major for incompatible changes, minor for backward-compatible features, and patch for backward-compatible fixes. A 0.y.z release is initial development and may change at any time; pre-release identifiers sort before the normal release, while build metadata does not affect precedence. Gem constraints express versions an application permits, but they cannot guarantee a gem author followed SemVer correctly—tests and lockfile review still matter.

Deep Dive & Architecture

SemVer works only when a project can identify its public API. That API may be code, a command-line interface, a data format, or documented behaviour. Refactoring private internals can remain a patch when users observe no changed contract; a one-line public removal can require a major release.

Pre-release identifiers communicate that a version may not satisfy the compatibility expectations of its normal release. Their parts participate in precedence comparisons. Build metadata identifies a build but is deliberately ignored for precedence, so two builds differing only after + have equal SemVer precedence.

A dependency range converts the upstream promise into local upgrade policy. A wide range makes fixes and features easier to receive but trusts more future releases. A narrow range reduces surprise but increases manual maintenance and resolution conflict. An application lockfile separates permission from timing by recording exactly when one allowed release was adopted.

Compatibility is contextual. Even a correct patch release can expose an application's accidental dependence on a bug, timing, or private API. Automated tests, deprecation review, and staged deployment are the evidence that a permitted version is safe for this application.

Code Example

require 'rubygems'

minor_range = Gem::Requirement.new('~> 2.3')
patch_range = Gem::Requirement.new('~> 2.3.4')

minor_range.satisfied_by?(Gem::Version.new('2.9.0')) # => true
minor_range.satisfied_by?(Gem::Version.new('3.0.0')) # => false
patch_range.satisfied_by?(Gem::Version.new('2.3.9')) # => true
patch_range.satisfied_by?(Gem::Version.new('2.4.0')) # => false

Common Mistakes & Pitfalls

Treating every version bump as risky (MINOR/PATCH should be safe), or bumping MAJOR for a small change (reserve it for breaking changes).