SimpleVersioning

Simple Versioning 0.1

Summary

Given a version number MAJOR.MINOR, increment the:

1. MAJOR version when you make incompatible API changes.
1. MINOR version when you make backwards-compatible changes.

Introduction

First, I want to thank Semantic Versioning for giving the world a tool to manage compatibility in software dependencies.

SemVer treats releases with new features separately from releases with bug fixes. For dependency management, that distinction isn’t important: all that matters is backwards compatibility. “Fixed a bug” and “Added a feature” are both examples of “made the software better”, as long as you didn’t break something. SimVer is meant to address that difference.

Simple Versioning Specification (SimVer)

SimVer is SemVer with these modifications:

1. A normal version number MUST take the form X.Y. X is the major version and Y is the minor version.
2. Minor version MUST be incremented for any release which maintains backwards compatibility to the public API.
3. Major version MUST be incremented if any backwards incompatible changes are introduced to the public API.
4. When compatibilty with SemVer tooling is required, it is acceptable to add a ‘.0’ patch version, e.g. 2.1.0, but normally that should be avoided.

Context

SimVer works best when bugs are very rare, when you release quickly/easily/safely, and when you don’t maintain released branches.

FAQ

As a consumer of an API, how can I make the most of SimVer?

• Always accept minor releases (e.g. specify 2.*)
• Update early and often.
• When you see deprecation warnings, update your code promptly.

What kinds of changes make good point releases?

• Bug fixes.
• New functionality.
• Marking old features as deprecated.

If even the tiniest backwards incompatible changes to the public API require a major version bump, won’t I end up with a large version number like 1337.0 very rapidly?

Sure. I don’t see this as a problem.

What about fixing security issues?

I’m tempted to say that security fixes can be minor releases, even if they break compatibility. Thoughts?

About

The Simple Versioning specification is authored by Jay Bazuzi.

If you’d like to leave feedback, please toot at me.

License

Creative Commons - CC BY 3.0