Semantic Versioning v0 Projects

- Dean Sofer -
Github.com/ProLoser

Versions are broken down by MAJOR.MINOR.PATCH

MAJOR: Backwards-incompatible changes / major refactor

MINOR: Backwards-compatible changes + new features

PATCH: Backwards-compatible fixes

Npm

Common dependency syntax

"*": any version

"^1.2.3": Any MINOR equal-to or greater than 1.2.3

"~1.2.3": Any PATCH equal-to or greater than 1.2.3

Dependency Resolution

// package1.json:
{
  "peerDependencies": {
    "mylib": "^1.2.3"
  }
}
// package2.json:
{
  "peerDependencies": {
    "mylib": "^1.4.5"
  }
}
// package3.json:
{
  "peerDependencies": {
    "mylib": "~1.6.7"
  }
}
// resolution:
{
  "dependencies": {
    "mylib": "1.6.14"
  }
}
  • Flexibility
  • Compatibility
  • Upgradeability
  • No Redundancy

Early Lifecycle Projects

  • Use 0.x.x versions
  • Frequent API changes
  • Frequent version changes
  • Lots of backwards incompatibility
  • Go to 1.0.0 once API stabilizes

So how do I version my project?

Early Lifecycle Problem

Backwards incompatible change: 0.1.0 => 1.0.0

  • Too early
  • Not stable yet
  • Lots of incompatible changes to come

Semver rapidly approaches: 42.0.0

Weird Dependency Behavior

// package1.json:
{
  "peerDependencies": {
    "mylib": "^0.2.3"
  }
}
// package2.json:
{
  "peerDependencies": {
    "mylib": "^0.4.5"
  }
}
// package3.json:
{
  "peerDependencies": {
    "mylib": "~0.6.7"
  }
}
// resolution:
{
  "dependencies": {
    "mylib": "ERROR"
  }
}

The Solution

Versions are broken down by MAJOR.MINOR.PATCH

MAJOR: 1.0.0 when API stabilizes

MINOR: Backwards-INcompatible changes + refactors

PATCH: Backwards-compatible features + fixes

Use MINOR for backwards incompatibility

Use PATCH for everything else

NPM dependencies behave differently for 0.x.x

"*": any version

"^0.2.3": Any PATCH equal-to or greater than 0.2.3

"~0.2.3": I've got no idea what this does

Dependency Resolution

// package1.json:
{
  "peerDependencies": {
    "mylib": "^0.2.3"
  }
}
// package2.json:
{
  "peerDependencies": {
    "mylib": "^0.2.5"
  }
}
// resolution:
{
  "dependencies": {
    "mylib": "0.2.14"
  }
}
  • Sensible resolutions
  • Flexible versioning
  • Enables consumption
    during early lifecycle

mind = blown

Feen

Made with Slides.com