04 October 2013

SemVer, an Versioning guidelines

http://semver.org/ is very simple, yet powerful versioning specs (guidelines) - you should read the whole page.

Highlights:

Given a version number MAJOR.MINOR.PATCH, increment the:
  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Example:


// suppose I've some software lib with the following code.
// current version 1.0.0
int sum (int x, int y){
    return x;    // note, buggy code
}

// I did a bugfix in backward compatible manner
// Clients Do *not* need to change in thier code to access same API
// version => 1.0.1
int sum (int x, int y){
    return x + y;
}

// I did add a logging feature in a backward compatible manner
// Clients Do *not* need to change in thier code to access same API
// version => 1.1.1
int sum (int x, int y){
    logger.info("client requests addition of " + x " and " + y);
    return x + y;
}

// I did an incompatible API change
// Clients Do needs to change in thier code to access same API
// version 2.0.0
int sum (int x, int y, Caller caller){
    logger.info("caller" + caller + " requests addition of " + x " and " + y);
    return x + y;
}

No comments: