Support development branches

[niemeyer]

This is a pain point that has shown up a few times and I think we should address, so here is the rationale and a candidate plan for it.

In a few cases I wanted to share an unstable sneak peak of the next API version. The most recent case at hand was the gopkg.in/qml.v0 => v1 migration. The problem was that the new project API version was still being worked on at a fast pace, breaking every day, and at the same time there were people interested in experimenting and helping out on the new API. This forced the early release of gopkg.in/qml.v1, with an unstable qml.v1/gl subpackage, which is not great and kills the expectation of stability that we want to create. This also sounds like a common problem, that we should address for everybody with a well known pattern rather than struggling every time.

So the current plan is to introduce support for vN-dev selector in URLs, which map to the vN*-dev tag/branch. In the example cited, this would allow the development of v1-dev publicly, while clearly marking the content as in-development. Once the daily breakages stop, it can be tagged/copied into the v1 release appropriately and as usual.

Please feel free to provide feedback here. If there are no major uncovered points, I'll work on this soon.

[slimsag]

Is there a purpose behind pkg.vN-dev versus just pkg.dev? I would think that at any time there would only be one in-development version of a package, and that upon release it would acquire the newest version number.

[nathany]

In my own case, I ended up having to make "v1" mean the api is different, not the api is stable. And the next api will be "v2" which means iterating version for every api change that is considered a release.

Thankfully pulling from master is still available and anything untagged can live there as "development".

The proposal is very much the release candidate functionality from SemVer. It would allow a v1-dev rc followed by v1, rather than stuff on master followed by v1 or calling the rc v1 and final v2 (even number stable releases).

It does add some complexity though, so I wonder if it's the best way to go?

[niemeyer]

@slimsag Even if we won't see multiple versions in development at once very frequently, the vN-dev tagging seems like a win in terms of clarity (it's the vN in-development).

@nathany That seems to indicate you are also suffering from the same issue, and are currently adopting a sub-optimal solution due to the lack of better support. How would someone tell that v2 is stable or not when looking at docs or the gopkg.in page? Those are good reasons towards implementing the vN-dev convention and support, so I think the fairly small added complexity is worth it.

[nathany]

So far I've only had the problem with going to v1 sooner than I would've liked. So yes, it would help. If you build it, I'll try it out. 😉

[nathany]

Warming up to this idea, the more I think about it.

In SemVer the pre-release can could be v1-dev or v1-rc.1 or whatever, so long as there is a hyphen:

1. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version.

I'm not sure if that's what we want or just -dev -- fine either way.

(In usage, I suspect -dev would be a branch until the final version is cut, whereas -rc.1 is a tag followed by -rc.2)

[dmitshur]

If someone wants to import the "latest in-development version" of a given package, could they not simply import the root source at "github.com/user/repo"? Assuming that its development takes place on master branch.

I suppose there'd be complications if the package imports subpackages (within same repo) that are versioned. In that case, I just want to say +1 to the issue and that some solution would be helpful.

[nathany]

Subpackages cause complications either way.

Looking at the amz library, the v2-dev branch still imports packages from v1, mixing code from both branches. I suspect it hasn't been fixed because of this issue. It's easy enough to change those imports.

amz has a default branch of v1. This means cloning the GitHub url will check out v1 for you. But it also means pull requests are opened against v1 by default. It might be more appropriate if they opened against v2-dev by default, as a working branch. The maintainers could choose whether to back port a change to v1. Of course this is really up to them, and master vs. v2-dev doesn't make much difference.

Due to #20, amz must still maintain a master branch even though it's not really needed. That adds some confusion to the whole thing.

I agree that v2-dev could be more clear to users of the package than master. For contributors, I'm less sure, perhaps they are equivalent?

[niemeyer]

@nathany Indeed, once this feature goes live (very soon!), the best approach is to hold the vN-unstable branch as the development focus where activities happen, and have a vN release branch that is tagged/merged to for release of the changes.

[dmitshur]

What about master branch? Will it still be necessary to have one for gopkg.in to work despite it being unused and irrelevant? Can master be used as vN-unstable branch?

[niemeyer]

The suffix was changed to "-unstable" in the implementation, as that's significantly more clear than "-dev" (we're all devs doing dev all the time).

[niemeyer]

@shurcooL That's issue #20 which will be fixed. No, vN-unstable maps to vN-unstable, which seems very clear and straightforward.

[dmitshur]

Thanks.

[AlekSi]

@niemeyer May you document "-unstable" suffix at http://labix.org/gopkg.in (redirected from http://gopkg.in)? (See #33)