Semantic Versioning (SemVer) Tutorial with Examples

Semantic Versioning (SemVer) is a versioning scheme designed to bring clarity and meaning to version numbers in software development. It provides a systematic way to convey information about changes in a release, helping developers and users understand the impact of updating to a new version.

Basics of SemVer:

SemVer version numbers follow the format: MAJOR.MINOR.PATCH. Let’s break down what each of these means:

• MAJOR version: Increased for incompatible API changes.
• MINOR version: Increased for backward-compatible new features or enhancements.
• PATCH version: Increased for backward-compatible bug fixes.

Additional Components:

• Pre-release versions (optional): Identified by appending a hyphen and a series of dot-separated identifiers. For example, 1.0.0-alpha.1.
• Build metadata (optional): Identified by appending a plus sign and a series of dot-separated identifiers following a hyphen or plus. For example, 1.0.0+20130313144700.

Examples:

Example 1: A Basic Release

Let’s say you have a library, and you are releasing the first version:

Version: 1.0.0

This signifies that it’s the initial release without any breaking changes, new features, or bug fixes.

Example 2: Adding a Feature

You add a new feature to your library without breaking existing functionality:

Version: 1.1.0

This indicates a MINOR version increase.

Example 3: Fixing a Bug

You fix a bug without changing existing features:

Version: 1.1.1

This results in a PATCH version increase.

Example 4: Incompatible API Changes

You make changes that are not backward-compatible:

Version: 2.0.0

This requires a MAJOR version increase.

Example 5: Pre-release Version

You are working on a new feature, but it’s not stable yet:

Version: 2.0.0-alpha.1

This indicates a pre-release version of the upcoming MAJOR release.

Example 6: Including Build Metadata

You want to include build information in your version:

Version: 1.0.0+20130313144700

This might include the date and time of the build.

Best Practices:

1. Follow SemVer strictly to provide clear versioning information.
2. Clearly communicate changes in your release notes.
3. Use tools that support SemVer for package management.

Conclusion:

Semantic Versioning is a valuable tool for developers and users to understand the implications of software updates. By following these guidelines and examples, you can ensure a consistent and meaningful versioning scheme for your software projects.