SemVer TLDR

Semantic versioning (SemVer) is a standard for defining the version numbers. A version number consists of three numbers separated by periods (.), e.g. 1.2.3.

X.Y.Z

Major (Breaking) X

• while being developed (i.e. before being officially released), this number is zero (0)
• when officially released, the number should increment to one (1)
• if a release breaks backwards compatibility, the number should increment by one and the following numbers reset to zero (e.g. 2.0.0)

Minor (Feature) Y

• when a new feature is added in a backwards compatible way, the number should increment by one and the following number reset to zero (e.g. 1.1.0)

Patch (Bugfix) Z

• when a bug is fixed, the number should increment by one (e.g. 1.0.1)

Example History of a Project

• 0.1.0 Development
• 1.0.0 Initial release (e.g. being used on a production site)
• 1.0.1 Fix bug where isPrime() returns true for negative numbers (e.g. -7)
• 1.1.0 Add new isPalindrome() function
• 1.1.1 Fix bug in isPalindrome() function to handle spaces (e.g. “taco cat”)
• 1.2.0 Add new isOdd() function
• 2.0.0 Remove isLucky() function (this function was included in the original release but is no longer supported)
• 2.0.1 Fix documentation around isLucky() removal

SemVer and the “Size” of Changes

A common pitfall when defining version numbers is wanting to define the version number based on the “size” of a change.

The number of lines changed has no impact on version number.

Major can be “Small”

A major version increase (e.g. from 1.3.5 to 2.0.0) can be as “small” as removing a single line of code.

A Bugfix can be “Large”

A bugfix version increase (e.g. from 1.3.5 to 1.3.6) could involve adding hundreds of lines of code.

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.