Semver?

[sdboyer]

though it's maybe not so hot in golang circles, semver is still pretty much the de facto norm for release versioning. i noticed the one tag that's present so far is 0.1, which isn't quite there (0.1.0 is probably the equivalent). for future releases, would you be OK with adopting semver?

like, once we finish this non-ts set implementation, a 0.2.0 would probably be in order. (or maybe a 1.0.0, if you feel like the API is stable.)

[fatih]

Yeah, semver seems ok. Just this package is already small, and even if we see a lot of iterations it's not going to be "1.0.0." in near future. That might confuse others when the see the package and say "ohh, it's still 0.2.3?!". But we can begin with 1.0.0, , non-tst would be 1.1.0 (bugfixes 1.1.x) and so on.

[fatih]

Would like to implement #17 before we decide on a Version.

[fatih]

I've just started it with v1.0.0 and removed the old tag from the remote, because gopkg.in was not supporting zero versions: https://github.com/fatih/set/tree/v1.0.0

I think it's good to. What do you think?

[sdboyer]

ack - if gopkg.in isn't supporting zero versions, then that's a definite bug. have you checked with niemeyer about it?

i don't think v1.0.0 is a good idea right now - in semver, a major version of 1 or greater means that we are promising we will keep the API consistent for everything under in that major version.

[fatih]

It does support it but it says:

Version zero (v0) is reserved for packages that are so immature that offering any kind of API stability guarantees would be unreasonable. This is equivalent to labeling the package as alpha or beta quality, and as such the use of these packages as dependencies of stable packages and applications is discouraged.

Don't you think this is harsh? I really don't want people discourage to use this package.

[sdboyer]

i do think that's perhaps a bit harsh in its phrasing - see semver: http://semver.org/, point 4. that's a better characterization of how i see semver applied in other language communities. to me, the only defining feature of a pre v1.0.0 package is that i cannot necessarily depend on its API, not really anything to do with extreme immaturity.

[niemeyer]

I'm happy to improve the description of v0 if we find a better wording. Can we please explore what's harsh about the current one, though? Breaking it apart, it says:

1. v0 is reserved for packages that are so immature that offering stability guarantees is unreasonable
2. It's equivalent to labeling it as alpha or beta quality
3. Using these packages as dependencies of stable packages and applications is discouraged

Point 1 is just an evident fact.. if it was reasonable, then it would not be v0. Point 2 also seems correct.. fast-evolving software without stability guarantees are generally labeled alpha or beta elsewhere. Point 3 is important.. if you use a package v0 as a dependency of a stable package or application, that application or package will break due to the lack of API stability of the underlying package, so it's not stable anymore.

So, it sounds fair, and somewhat demoted of harshness. But I might be missing something?

As another point, is there any reason for not labeling the set package as v1 right away, if you're already happy enough with the current API? There's nothing preventing it from changing to v2 when the time comes. Putting one stable API doesn't mean you cannot upgrade to another stable API eventually. It just tells people "I'll not break your application after you link with this, unless I make a mistake".

[sdboyer]

@niemeyer - fair, we could just keep the v1.0.0 tag and then retag with a v2.0.0 shortly. my justification for not doing it is simplicity for users - since this library hasn't tagged anything up till now, tagging now when we have impending changes that will change the public API seems to invite confusion, when we could just as well wait a couple days, then tag the v1.0.0 with those changes. and that would still make a v0 series tag now accurate.

as for the language of gopkg.in, my only real concern is that i would prefer to not necessarily associate a pre v1.0.0 tag with something being immature: the sole signal should be, "i do not yet guarantee this API to be stable." not yet being mature is the primary reason one wouldn't yet apply a v1 series tag, but i'd rather people just focus on the "i don't guarantee this API just quite yet" than infer something about the maturity of the package as a whole.

eh...maybe i'm splitting hairs.

[fatih]

Reading the sentence for Zero Version together with the words "immature, alpha, discouraged" all toghether make me feeling bad about marking it directly with tag v0.1.0 :) But all the points you made are also valid. It was just a minor concern and not a big deal. I believe we could make it that it doesn't sound so bad.

@sdboyer I can do remove the tag, apply it as v0.1.0 and use the import path gopkg.in/fatih/set.v0 until we decide to mark it as stable. I think this would also give us more flexibility to implement the things in the issues list, (like new New() constructor, or sorting).

[FriarTech]

I see both points. I liked the idea of not stating it's version 1 yet. But then again - (and because Im just getting involved in the project) its sortofa misnomer because it is in a usable state. Maybe instead of making immediate changes like sort, and new, we start with making a list for upcoming features. Then we tag the list items as major/minor revisions (in other words, what changes would break api, which changes wouldnt) then slate them for work to be done. If version 1 tagging will get more people to use it - Im for that.

[sdboyer]

yeah, i could really go either way at this point. i think it comes down to, if we keep the current v1.0.0 tag, then we need to get a little more deliberate about managing changes, in the way @FriarTech describes.

[niemeyer]

@sdboyer

as for the language of gopkg.in, my only real concern is that i would prefer to not necessarily associate a pre v1.0.0 tag with something being immature: the sole signal should be, "i do not yet guarantee this API to be stable." not yet being mature is the primary reason one wouldn't yet apply a v1 series tag, but i'd rather people just focus on the "i don't guarantee this API just quite yet" than infer something about the maturity of the package as a whole.

The project cannot be mature if its API is immature. People's code will break if the API mutates while they're depending on it.

The feeling I have from this conversation is that the information provided in the description of v0 in gopkg.in is proving useful. The best course of action is to fix the few issues in the current API, and then brand it as v1 so people can more easily depend on the package not breaking arbitrarily. This will encourage its use, both because the API will be better, and because people will have a good feeling about trusting on authors that do an effort to not break their dependents.

[niemeyer]

And again, if you need more changes down the road, just label it as v2 and move on. The great thing about using such a scheme is that it provides freedom to both sides.

[FriarTech]

Um. Does this last commit need a lightweight tag or branch tag? I just tried installing set with the gopkg.in instructions, and the old README.md got downloaded. (the one without the new gopkg.in instructions)

[niemeyer]

If you use a v0 or v1 branch, you can make it the default in GitHub going to the Settings page. This way the README.md and everything else will be reflected out of that branch.

[fatih]

@FriarTech can you try again? The tag was based on the not updated Readme.md commit which I've fixed now

@niemeyer thanks for tips, we'll do it definetely.

And for the version, I'm up to you guys, I say let's stay at v0.1.0, mark it as gopkg.in/fatih/set.v0, implement the changes together with a roadmap and then release it as v1.0.0 Please vote and let us move forward.

My vote is for v0.1.0 :+1:

Also I think we can move this project to github.com/go-set and mark it as an organization where we could help each other :)

[sdboyer]

@niemeyer - maybe a tad reductionist, but this is an area where ambiguity isn't great. i relent :)

[FriarTech]

I like it! I like it! My vote is in. Tonight I'll get the new new hopefully up for review.

[FriarTech]

The new readme.md came down the pipe.

[fatih]

It's now tagged to v0.1.0 and can be reached with:

import "gopkg.in/fatih/set.v0"

Closing this, thanks for all for contributing.