versioning and tagging releases

[willnorris]

We generally try not to have egregious breaking changes in this library, but we're also not afraid to do them when necessary (the latest example being #375). We've gotten a couple of people asking for us to use semver on google/go-querystring#11, which we could also consider doing here.

That doesn't help us for #375, but would allow us to do future breaking changes at a version boundary. I have no intention of changing the import path to use gopkg.in or anything like it, but it would still help set appropriate expectations for folks when they do upgrade to a new version. And keeping a CHANGELOG.md file might be nice (although a bit of work to keep up to date) to point out new APIs that we support, etc.

@gmlewis @shurcooL what do you think?

[parkr]

To me, vendoring makes this a moot issue - users can upgrade when they are ready and vendor the version they wish to use. This is ideal, however, and does not represent everyone's workflow. But it is something to suggest as people come pointing fingers about blame.

I had a package break due to the addition of a parameter to PullRequestsService.Merge. I fixed it and moved on. Go makes it very easy to deal with small breaking changes like that.

Moving the canonical source to gopkg.in is, in itself, a breaking change, right? Now that Go forces you to use the canonical import path?

[gmlewis]

I suppose there are varying levels of supporting semantic versioning as well.
The bare minimum is to have a file somewhere in the repo with a version string in it.
A step up would have a compiled file with a const string in it that gets bumped.

This repo already has libraryVersion which appears to have remained at 0.1 since the beginning.

On other projects that I supported, maintaining a CHANGELOG.md was a pain and I always wondered if anyone ever really looked at it or found it useful.

All that said, I don't have really strong opinions either way.

My recommendation moving forward is to bump libraryVersion to 0.2 in #375 since it is a breaking change and let the commit message suffice for the change log. Let people vendor the library as they see fit.

[willnorris]

Moving the canonical source to gopkg.in is, in itself, a breaking change, right?

In case you misread, I have zero intention of moving to gopkg.in. I think it's a clever service and I greatly respect Gustavo, but I'm not about to add an extra single point of failure that I have no control over to how people access this package if I don't have to. And I definitely don't want to cede control of the namespace; I actually don't even like "github.com" in the import path either (as you know from my personal packages), but I don't have a good Google controlled hostname that would work well for this. And as you point out, vendoring mostly obviates the need for a service like gopkg.in.

All that said, there are still other advantages to versioning and tagging the library, some hypothetical/theoretical, some practical.

• A tagged release my carry with it some extra assurance of stability or having been more thoroughly tested (for example, running go 1.6.x versus tip). That's not really an issue with go-github, since we tend to keep master well tested.
• As pointed out in please tag and version this project go-querystring#11 (comment), glide supports semver similar to Gemfiles where you can specify a major version you want and it will always grab the latest within that range.
• Even if you're not using glide (or any other vendoring tool for that matter), sticking to semver sends a signal as to what users of the library can expect (in terms of compatibility) from a given release.

Now even with that said, I don't typically version my go libraries because I always vendor anyway, and versioning is not all that common in the go community. And I don't relish the idea of trying to keep a changelog up to date, making decisions about version numbers, etc.

[dmitshur]

I don't have strong opinions, but I would hope we lean towards doing the simpler thing. A more complex solution IMO is going to add overhead and little actual benefit.

My recommendation moving forward is to bump libraryVersion to 0.2 in #375 since it is a breaking change and let the commit message suffice for the change log. Let people vendor the library as they see fit.

I agree with this recommendation, but minor tweak. Maybe just make it an integer and increment it by 1 with every breaking API change (so, make it "2"). I don't think it's valuable for us to track the minor and patch parts of semver with every commit.

We have great commit messages, let's keep that up.

We may make some minor breaking API changes, but only when it makes sense, leads to a better API, and isn't hard to update. If you're vendoring go-github, you update whenever you want and re-vendor. If you choose not to vendor (knowing the risks and choosing to accept them), you update right away. The API of this package is quite mature and unlikely to change or evolve significantly in the future.

[dmitshur]

Another observation is that this library tends add support for new GitHub API features while those are still in preview, which means if you choose to use those features, they may break at any point. That just goes without saying, but I guess I'm saying it anyway. If you need full reliability at all times, you must vendor go-github AND not use any of the preview API endpoints.

[willnorris]

sounds good to me... we'll leave things as they are.

[willnorris]

A timely post: http://dave.cheney.net/2016/06/24/gophers-please-tag-your-releases

[dmitshur]

I wonder if @davecheney has seen this thread when writing that.

[jredville]

I was going to make a big comment after my request for versioning go-querystring was closed, but Mr. Cheney covered my thoughts pretty well.

[davecheney]

That's Mr. Cheney.

On Sat, 2 Jul 2016, 01:19 Jim Deville notifications@github.com wrote:

I was going to make a big comment after my request for versioning
go-querystring was closed, but Cheney covered my thoughts pretty well.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#376 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAAcAz2_Mi87Pp6RTFvkNRtKZdzRaPwcks5qRS_-gaJpZM4I4qYJ
.

[mh-cbon]

Hi,

I d like to re open that issue. As i faced a build issue with your repo because i basically can t track it via semver.
I m using glide, and yeah, despite all, this particular case where a dependency relies on a commit is not handled in a satisfactory way.

Whatever, i m just arguing that having a git tag x.x.x is not an overwhelming load in your process.

I d like also to point out that i developed method to help to manage a changelog, version bumping and so on.

this or that, please consider tagging your git.

[willnorris]

Reopening this discussion, particularly in light of the direction that https://github.com/golang/dep is taking. It will support specifying specific versions of dependencies, presumably relying on git tags, though I haven't tried it out yet. See also my comment in #529 that I'm not sure that the libraryVersion const is actually doing us any good since it doesn't protect against build breakages.

To @shurcooL's point above, if we go this route, we will need to decide (and document) when we bump which version numbers. semver is pretty clear on most of that, but what about the preview APIs? Do we explicitly call them out in the godocs and say that they are excluded from any versioning policy?

This is somewhat complicated by the fact that many of our standard API calls are actually using a preview media type in order to get some different behavior or extra information in the response. In those cases, do we say that only the subset of behavior or fields are excluded from the versioning policy? (I think the answer has to be "yes", since otherwise we could be taking a previously stable method and regressing it back to preview status).