Multi-Variance: API Versioning For Software Libraries

A presentation by @stuherbert  for @GanbaroDigital Multi-Variance API Versioning For
Software Libraries

Industry veteran: architect, engineer, leader, manager, mentor F/OSS contributor since
1994 Talking and writing about PHP since 2004 Chief Software Archaeologist Building Quality @GanbaroDigital About Stuart

Follow me I do tweet a lot about non-tech stuff
though :) @stuherbert

@GanbaroDigital ?? ?? Do you create and publish Composer packages?

@GanbaroDigital ?? ?? What versioning scheme do you use?

@GanbaroDigital ?? ?? Have you ever put out a new
version of your package with substantial b/c breaks?

@GanbaroDigital I'm here to talk about the consequences of b/c
breaks in packages.

@GanbaroDigital And to share a different approach from my own
packages.

@GanbaroDigital This is just my own approach. Other approaches exist.
I'm here to learn from you too!

@GanbaroDigital In This Talk ... 1. Semantic Versioning 2. Modularity
3. Consequences 4. Library Packages 5. Dev Tools

@GanbaroDigital Current Practice

@GanbaroDigital Semantic Versioning

@GanbaroDigital semver.org

@GanbaroDigital X.Y.Z versioning scheme

@GanbaroDigital X.Y.Z major.minor.patchlevel

@GanbaroDigital Fix a bug? Increment Z. e.g. 1.1.0 -> 1.1.1

@GanbaroDigital Add a new feature? Increment Y, reset Z. e.g.
1.1.1 -> 1.2.0

@GanbaroDigital Add a major feature? Or break backwards-compability? Increment X,
reset Y & Z. e.g. 1.2.0 -> 2.0.0

@GanbaroDigital semver is a modern take on old-skool versioning.

@GanbaroDigital ?? ?? Why semver?

@GanbaroDigital The semver rules are a contract between package maintainers
and library users.

@GanbaroDigital “Library users should be able to upgrade to the
latest X.*.* release without changing their code.

@GanbaroDigital e.g. 1.0.0 -> 1.59.46 should be a hands-off upgrade.

@GanbaroDigital That is a very high bar for package maintainers
to meet.

@GanbaroDigital Why? Because of backwards-compatibility breaks.

@GanbaroDigital ?? ?? What is a backwards-compatibility break?

@GanbaroDigital Changing any existing API.

@GanbaroDigital Changing the behaviour of any existing API.

@GanbaroDigital Fixing a bug.

@GanbaroDigital Adding deprecated warnings to any existing API.

@GanbaroDigital Changing the package's dependencies.

@GanbaroDigital Changing the supported PHP version(s).

@GanbaroDigital Breaking b/c has major consequences for library-users.

@GanbaroDigital That's why the semver rules require package maintainers to
bump the 'X' version number.

@GanbaroDigital ?? ?? What's the knock-on effect if you change
your package's major version number?

@GanbaroDigital Hold that thought. We'll answer that a little later
on.

@GanbaroDigital Modularity

@GanbaroDigital Most mainstream programming languages are not modular.

@GanbaroDigital Libraries are loaded into a shared symbol table.

@GanbaroDigital Schemes like namespacing still use the shared symbol table.

@GanbaroDigital Schemes like 'friends' simply add access controls. They don't
partition the shared symbol table.

@GanbaroDigital ?? ?? Which mainstream programming language is modular?

@GanbaroDigital JavaScript*

@GanbaroDigital ?? ?? The reason your node_modules folders are gigabytes
in size?

@GanbaroDigital npm* supports installing different versions of the same package
into the same app.

@GanbaroDigital Composer cannot. Because the language isn't modular.

@GanbaroDigital This is not a PHP problem. Nearly all mainstream
programming languages share this limitation.

@GanbaroDigital I'm not here to debate modular vs non-modular.

@GanbaroDigital PHP is a non-modular language. It's going to stay
that way for the foreseeable future.

@GanbaroDigital I want to look at how we work with
the cards we've been dealt.

@GanbaroDigital Consequences

@GanbaroDigital ?? ?? What's the knock-on effect if you change
your package's major version number?

@GanbaroDigital If you've used popular Composer packages such as Guzzle,
or PHPUnit ...

@GanbaroDigital ... you'll have seen errors like this: "Can only
install one of: guzzlehttp/guzzle[6.1.0, 5.3.0]"

@GanbaroDigital “Two different major versions of the same package cannot
co-exist inside the same app.

@GanbaroDigital The more popular your package, the more likely it
is to be pulled into the same app multiple times.

@GanbaroDigital ?? ?? As a library-user, how do you solve
this?

@GanbaroDigital You can't.

@GanbaroDigital ?? ?? As a package maintainer, how can you
avoid this?

@GanbaroDigital Multi-variance

@GanbaroDigital Library Packages

@GanbaroDigital In any non-modular language, only one version of your
package can exist inside any one app.

@GanbaroDigital That's our design constraint. We cannot change it. We
have to work with it.

@GanbaroDigital ?? ?? Do you build web APIs?

@GanbaroDigital If you're building a web API, you support multiple
versions of your API at the same time.

@GanbaroDigital So why not do the same with library APIs?

@GanbaroDigital There's nothing stopping you from having multiple versions of
your API inside one package.

@GanbaroDigital my-package

@GanbaroDigital my-package src

@GanbaroDigital my-package src/V1

@GanbaroDigital my-package src/V1 src/V2

@GanbaroDigital "autoload": { "psr-4": { "GanbaroDigital\\TextParser\\V1\\": "src/V1", "GanbaroDigital\\TextParser\\V2\\": "src/V2" }
}

@GanbaroDigital We can't use semver for our package version numbers.
But package managers expect semver-like version numbers.

@GanbaroDigital Version numbers change from X.Y.Z to X.datereleaseno

@GanbaroDigital e.g. from 1.2.0 to 1.2018082601

@GanbaroDigital X is the minimum supported API version

@GanbaroDigital Bump X when you drop support for an API
version.

@GanbaroDigital (but be prepared for all the consequences I've already
discussed!)

@GanbaroDigital the datereleaseno is the year, month, day + how
many releases you've made that day

@GanbaroDigital e.g. 1.2018082601 1.2018082602 1.2018082801

@GanbaroDigital ?? ?? Why not X.date.releaseno? e.g. 1.20180826.01?

@GanbaroDigital You want the dependency rules to always pull in
new releases of X.*.

@GanbaroDigital e.g. 1.2018082601 -> 1.2018082602 1.2018082602 -> 1.2018082801

@GanbaroDigital With X.date.release, there's a risk of users adding dependency
rules that lock them into X.date.* releases!

@GanbaroDigital e.g. 1.20180826.01 would they get 1.20180828.01?

@GanbaroDigital This approach is what I call multi-variant packages: multiple
API versions inside the same package.

@GanbaroDigital ?? ?? Does anyone remember how Guzzle solved this?

@GanbaroDigital Dev Tools

@GanbaroDigital Here, we're talking about tools like PHPUnit. Something you
install that provides new CLI commands.

@GanbaroDigital ?? ?? What problems do these CLI tools cause
w.r.t. package version clashes?

@GanbaroDigital They pull in dependencies of their own, which can
clash with your app's dependencies. (Or with the dependencies' dependencies!)

@GanbaroDigital ?? ?? How would you solve that?

@GanbaroDigital Package maintainers: Ship these tools as PHAR ﬁles.

@GanbaroDigital End-users: download and use the PHAR ﬁles.

@GanbaroDigital

Thank You How Can We Help You? A presentation by
@stuherbert  for @GanbaroDigital

Multi-Variance: API Versioning For Software Libraries

Multi-Variance: API Versioning For Software Libraries

More Decks by Stuart Herbert

Other Decks in Programming

Featured

Transcript