Stability and Semantic Versioning Demystified Lone Star PHP April 26th, 2014

Beau Simensen @beausimensen +BeauSimensen beau.io

Dragonfly Development @dflydev dflydev.com

boogio.com @wearboogio reflxlabsinc.com @reflxlabs

No content

{ “name”: “acme/my-project”, “description”: “Acme’s My Project”, “license”: “MIT”, “require”: { “silex/silex”: “1.1.*” }, “autoload”: { “psr-4”: { “Acme\\MyProject\\”: “src” } } }

$ composer install Loading composer repositories with package information Installing dependencies (including require-dev) - Installing psr/log (1.0.0) - Installing symfony/routing (v2.3.7) - Installing symfony/debug (v2.3.7) - Installing symfony/http-foundation (v2.3.7) - Installing symfony/event-dispatcher (v2.3.7) - Installing symfony/http-kernel (v2.3.7) - Installing pimple/pimple (v1.1.0) - Installing silex/silex (v1.1.2) Writing lock file Generating autoload files $

Semantic Versioning

semver.org

MAJOR.MINOR.PATCH Which number do you increment and why?

MAJOR.MINOR.PATCH When you break backwards compatibility

MAJOR.MINOR.PATCH When you add backwards compatible features

MAJOR.MINOR.PATCH When you make backwards compatible bug fixes

Pre-Release Identifiers

1.0.0-alpha 1.0.0-beta.2 1.0.0-RC3

Stability Pre-Release Identifiers

Version Constraints

Exact Version 1.0.2

Ranges >=1.0,<2.0

Wildcards 1.0.*

Next Significant Release Tilde Operator

Next Significant Release ~1.2 Minimum allowed version and only the last number listed can increase.

Next Significant Release ~1.2 >=1.2,<2

Next Significant Release ~1.2.3 >=1.2.3,<1.3

Semantic Versioning lets you know what you are getting into

Safe 1.3.* Only get bug fixes

Reasonably Safe 1.* Get bug fixes and new features

Crazy Sauce * Composer allows this, but don't. Just don't.

Version Constraint Considerations

–Semantic Versioning “If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package).”

Libraries should generally have more permissive constraints

–Semantic Versioning “If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable).”

End projects may want to have more restrictive constraints

Deep Dependency Resolution

{ “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1

{ “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “~1.1”, “doctrine/orm”: “~2.3” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1 2.3.2 2.4.0 2.3.1 2.3.0 2.2.1 2.5.0 ORM 2.2.0 1.0.0 dflydev

{ “name”: “acme/myapp”, “require”: { “dflydev/doctrine-orm-service-provider”: “1.0.*”, “silex/silex”: “1.1.*”, ! “pimple/pimple”: “~1.1.1”, “doctrine/orm”: “2.4.*” } } { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “~1.1”, “doctrine/orm”: “~2.3” } } 1.1.0 1.1.0 1.1.1 1.0.2 1.0.1 1.0.0 2.0.0 Silex Pimple 0.0.1 2.3.2 2.4.0 2.3.1 2.3.0 2.2.1 2.5.0 ORM 2.2.0 1.0.0 dflydev 1.0.0 myapp

Conflicts

{ "require": { "silex/silex": "1.1.*", "pimple/pimple": "2.0.*@dev" } }

$ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. ! Problem 1 - silex/silex v1.1.0 requires pimple/pimple 1.* -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - silex/silex v1.1.1 requires pimple/pimple 1.* -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - silex/silex v1.1.2 requires pimple/pimple ~1.0 -> satisfiable by pimple/pimple[1.0.0, 1.1.x-dev, v1.0.1, v1.0.2, v1.1.0]. - Can only install one of: pimple/pimple[2.0.x-dev, 1.0.0]. - Can only install one of: pimple/pimple[2.0.x-dev, 1.1.x-dev]. - Can only install one of: pimple/pimple[v1.0.1, 2.0.x-dev]. - Can only install one of: pimple/pimple[v1.0.2, 2.0.x-dev]. - Can only install one of: pimple/pimple[v1.1.0, 2.0.x-dev]. - Installation request for pimple/pimple 2.0.*@dev -> satisfiable by pimple/pimple[2.0.x-dev]. - Installation request for silex/silex 1.1.* -> satisfiable by silex/silex[v1.1.0, v1.1.1, v1.1.2]. ! Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting.

Versions from Tags

2.0.1 2.0.1 (2.0.*)

v2.0.1 2.0.1 (2.0.*)

2.0.1-RC1 2.0.1-RC1 (2.0.*@RC)

3.4-cuddly-cat 3.4-cuddly-cat (3.4-cuddly-cat)

2.0.1g 2.0.1g (2.0.1g)

Versions from Branches

Branches are considered @dev stability

Numbered branches are easy

2.0 2.0.x-dev (2.0.*@dev)

Named branches default to their name with a dev- prefix

master dev-master (dev-master)

2.0-experimental dev-2.0-experimental (2.0.*@dev won't work!)

Named branches can be aliased to be semver friendly

{ “extra”: { “branch-alias”: { “dev-master”: “2.0.x-dev” } } }

master dev-master / 2.0.x-dev (dev-master or 2.0.*@dev)

Create a branch alias as soon as you start a new Composer package

(future you and your users will thank you)

Requiring non-stable versions

{ “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }

{ “require”: { “symfony/yaml”: “3.5-cat”, “silex/silex”: “1.1@dev”, “pimple/pimple”: “dev-master”, “sculpin/core”: “2.0.*@beta” } }

requiring dev-master considered harmful

Pretend dev-master doesn't exist

Send pull requests when you find a package that offers dev-master without a branch alias

{ “name”: “acme/myapp” }

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, ! “ircmaxell/random-lib”: “@dev” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, ! “ircmaxell/random-lib”: “dev-master” } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } }

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, "dflydev/hawk": "1.0.*", ! "ircmaxell/random-lib": "dev-master" } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } } ! ! { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } }

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: "1.0.*”, "dflydev/hawk": "1.0.*", ! "ircmaxell/random-lib": "dev-master" } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “dev-master” } } ! ! { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } 1.0.x-dev != dev-master

{ “name”: “acme/myapp”, “require”: { “naughty/id-generator”: “1.0.*”, "dflydev/hawk": "1.0.*", ! "ircmaxell/random-lib": "@dev" } } ! ! { “name”: “naughty/id-generator”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } ! ! { “name”: “dflydev/hawk”, “require”: { “ircmaxell/random-lib”: “~1.0@dev” } } Time to send a pull request!

dev-master is a virus

Once people start using dev-master for your package it can be hard to break them of that habit

Send pull requests when you find a package that requires dev-master when a branch alias exists

–Michael Dowling “I'm working on a new version of Guzzle. If you're using composer: stop using dev-master. Use a tagged release. Especially in production.” https://twitter.com/mtdowling/status/440901351657054208

Stability

Root package

The root package is the package defined in the working composer.json

A package is the root package while it is being developed

The root package gets to control all aspects of stability

Minimum stability

Controlled by the root package

Defaults to stable

{ “minimum-stability”: “alpha” }

Applied to all packages for which the root package doesn't specify a stability

Package-by-package stability

Stability can be controlled on a package-by-package basis

{ “require”: { “silex/silex”: “~1.1@dev”, “symfony/http-foundation”: “@beta” }, “minimum-stability”: “alpha” }

Stability solver errors are fun

{ "require": { "sculpin/sculpin": "2.0.*" } }

$ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. ! Problem 1 - The requested package sculpin/sculpin 2.0.* could not be found. ! Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting

$ composer install Loading composer repositories with package information Installing dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. ! Problem 1 - The requested package sculpin/sculpin 2.0.* could not be found. ! Potential causes: - A typo in the package name - The package is not available in a stable-enough version according to your minimum-stability setting

{ "require": { "sculpin/sculpin": "2.0.*@dev" } }

{ "require": { "sculpin/sculpin": "2.0.*" }, "minimum-stability": "dev" }

Root package stability implications

Even if your package requires a dependency @dev, users of your package won't get it unless they explicitly ask for it.

{ “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } Root Package

{ “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “1.*@beta”, “silex/silex”: “1.1.*”, “doctrine/orm”: “~2.3” } } Root Package

{ “require”: { “dflydev/doctrine-orm-service-provider”: “1.0.*”, ! “pimple/pimple”: “1.*@alpha” } } { “name”: “silex/silex”, “require”: { “pimple/pimple”: “1.*@dev” } } { “name”: “dflydev/doctrine-orm-service-provider”, “require”: { “pimple/pimple”: “1.*@beta”, “silex/silex”: “1.1.*”, “doctrine/orm”: “~2.3” } } Root Package

[this page intentionally left blank]

Semantic Versioning lets you know what you're getting into

Libraries should generally have more permissive constraints

End projects may want to have more restrictive constraints

Create branch aliases

dev-master considered harmful

#composer look for simensen and say "hi" freenode IRC

Questions? @beausimensen +BeauSimensen ddd.io/lsp14-semver joind.in