API break in v1.2.0

[twilly]

debounce's New function changed its signature. This release was tagged as a semver'd v1 release but this signature change is API incompatible. This API change should have been tagged as v2.0.0.

Dependency managers (eg dep / go modules) may choose upgrade debounce from v1.1.0 to v1.2.0. Code that relies on the v1.1.0's New will now fail to compile.

An example break is with Hugo. Hugo v0.54.0 depends on debounce and was released with debounce v1.1.0. This works fine if I start a project and install Hugo.

tristan@dashie:~/go/src/example.com/foo$ go version
go version go1.12.1 linux/amd64
tristan@dashie:~/go/src/example.com/foo$ export GO111MODULE=on
tristan@dashie:~/go/src/example.com/foo$ go mod init
go: creating new go.mod: module example.com/foo
tristan@dashie:~/go/src/example.com/foo$ go run github.com/gohugoio/hugo
Total in 0 ms
Error: Error building site: open /home/tristan/go/src/example.com/foo/content: no such file or directory
exit status 255

But if I update dependencies, debounce v1.2.0 will come in and Hugo breaks.

tristan@dashie:~/go/src/example.com/foo$ go get -u github.com/bep/debounce
tristan@dashie:~/go/src/example.com/foo$ go run github.com/gohugoio/hugo
# github.com/gohugoio/hugo/commands
../../../pkg/mod/github.com/gohugoio/hugo@v0.54.0/commands/commandeer.go:146:26: assignment mismatch: 3 variables but debounce.New returns 1 values

[bep]

v1.2.0 was mainly a bug fix release, so not going v2 was the correct thing to do. Had I known that other people also used this library, I might have gone the extra mile to avoid API breakage (which would have made it v1.1.1), but that train has gone.

All Go dependency managers I know of have ways to pin a certain version, if that is what you really want.

[twilly]

Sorry if my example is a little terse and specific. I wanted the issue to be precise and accurate for this library.

Taking this to a higher level, I'm not depending on debounce directly. I encountered this break in one of my projects where I wrap Hugo.

The first time I generated a lock was fine at the time. Today I cannot run an update as this and a few other libraries broke the version of Hugo being used*. I tried updating to the latest Hugo v0.54.0, but Hugo v0.54.0 isn't pinned down debounce 1.1.0. I'm stuck manually specifying pins on transitive dependencies since there's no recent tagged release of Hugo. An alternative I'm considering is vendoring at Hugo master to be a bit more future proof.

A way out of this semver barn is to release v1.2.1 without the API change and then make a v2.0.0 release with the incompatible API change. v1 can be left alone and new development can go as v2. I'd be happy to make a PR to do the ground work if you'd like.

* Example: github.com/spf13/jwalterweatherman also broke between v1.0.0 to v1.1.0 when Notepad.LogCountForLevelsGreaterThanorEqualTo was removed. I have four pins so far to get Hugo v0.54 building while allowing me to update my other direct dependencies.