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).

[parkr]

Instead of using SemVer, which greatly complicates things and will favor backporting, simply tag chunks of changes as v1, v2, v3, etc and allow people to upgrade to discrete points in time, as requested. Anytime you have N commits on master, you could automatically tag a new release. There would be no "minor" or "patch" releases, as they complicate things for the end user and for maintainers. 💭

[dmitshur]

The preview APIs definitely complicate matters. It seems we have two options:

1. Bump the version only when the subset of our API that does not use preview headers changes, and document that this version is only valid for people that don't use any of preview endpoints.
2. Bump the version for any breaking API change, even if it's a preview endpoint.

I imagine for some users that care about the utmost stability, they would only use stable endpoints and benefit from first option more.

Many other users end up being more practical, have a higher tolerance for instability and choose to use some preview endpoints, and they would benefit more from second option.

I'm leaning slightly towards the second option, and we can leave comments about whether the breaking change affects preview endpoints or stable endpoints. But not sure.

[willnorris]

Instead of using SemVer, which greatly complicates things and will favor backporting, simply tag chunks of changes as v1, v2, v3, etc and allow people to upgrade to discrete points in time, as requested. Anytime you have N commits on master, you could automatically tag a new release. There would be no "minor" or "patch" releases, as they complicate things for the end user and for maintainers. 💭

Nothing in semver says when you have to cut releases. So we could simply decide to only cut releases at major versions and call them v1.0.0, v2.0.0, etc. That would achieve the same result and still be semver compatible.

I'm not entirely sure we want to do that (only tag at major versions), but it's at least an option.

[willnorris]

@shurcooL or a third option, if we're willing to deal with both major and minor versions:

a) major version is bumped with any breaking change to non-preview functionality, including changes to function signatures or behavior.
b) changes to preview functionality would only require a minor version bump. The non-preview functionality hasn't changed, so does not necessitate a major version bump, but by cutting a new minor release it gives us an opportunity to call out what new APIs have been added, etc. The frequency of cutting these releases is of course at our discretion... maybe queue them up for a bit so it doesn't add too much overhead.

[willnorris]

Instead of using SemVer, which greatly complicates things and will favor backporting

Semver doesn't imply any level of support or backporting of bug fixes onto older branches. I would be completely fine saying that we only focus on supporting master (and maybe the latest tagged release). Older releases are simply there as a convenience to avoid the inevitable breakages that will happen when you build against master.

And if golang/dep adopts semver, which it sounds like they will, then we may not have a choice but to follow suit (which I'm fine with).

Also, it could be said that older versions come with the exact same level of support as the master branch... none at all. (Or "best effort" if you prefer.)

[willnorris]

Any other final thoughts on this topic? I haven't heard adamant opposition to moving forward with semver tagging, so I'm going to plan on that being the path forward. I'll put together a PR that updates our docs to talk about how we handle versioning.

[dmitshur]

Can you quickly summarize the final semver scheme you're thinking of going with? We've discussed at least 3 options above, so I'm not sure which one you're referring to.

[RaviTezu]

Hi @willnorris @shurcooL, Is something finalized on this? If yes are we tracking it somewhere else? Also, I want to know if there's anything I can help with :)

[dmitshur]

I'm waiting on a summary of the final semver scheme that @willnorris had in mind. It's a little hard to deduct from reading the comments above, because a lot of different options were being discussed with back and forth.

[willnorris]

yep, this is squarely on me. I'll try and carve out some time soon.