search

jbenet / random-ideas

random ideas
juan.benet.ai
324 stars 12 forks source link

JRFC 35 - Vanity Semver #35

Open jbenet opened 8 years ago

jbenet commented 8 years ago

(I suggested this a long time ago. It has also been suggested by other people, likely before me).

If you're shipping products with (non-developer) end-users who don't care about API changes, don't confuse them with raw semver, use vanity-semver!

<vanity>.<semver>

<vanity>.<major>.<minor>.<patch>

the change is simple: add a <vanity>. prefix that represents the version that end users should care about. most of the time this will just be 1.. But sometimes, when undergoing a fundamental product change (like OS X), it is useful to let end-users know that the thing is fundamentally better now, and that they should try it again. (or maybe it's even a sequel! \o/)

Basically, <vanity>. should change little enough to be safe to put in print. Yes, physical paper physically printed-on and shipped physically to analog humans. If it makes you uneasy to print + mail a version number to users, maybe use <vanity>..

It is recommended that end (non-developer) users see:

semver is awesome and super useful. But it has one problem. things end up at high major version numbers (90.0.1!) pretty quickly.

The spec says:

Doesn't this discourage rapid development and fast iteration?

Major version zero is all about rapid development. If you're changing the API every day you should either still be in version 0.y.z or on a separate development branch working on the next major version.

If even the tiniest backwards incompatible changes to the public API require a major version bump, won't I end up at version 42.0.0 very rapidly?

This is a question of responsible development and foresight. Incompatible changes should not be introduced lightly to software that has a lot of dependent code. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means you'll think through the impact of your changes, and evaluate the cost/benefit ratio involved.

Basically, release a breaking change once you're really, really sure of it (work on separate branches and only make few major releases! this fits github's API semver, which i think is still on V3. good responsible citizens! :+1:).

I very much agree with TPW. But the reality is that people don't do this for the majority of projects... at all. modules all over the place (both libraries and programs) evolve very quickly, and sometimes a single deprecation causes a major bump. Which is the right thing to do when using semver. Major MUST be bumped. But this is often at odds with the intention of responsible developers with large non-dev audiences.

Ok, so we have a huge version number, so what?

That sucks for non-developer end users.

If you couple the API version (which is what semver is: a version of the API of the {module, program, restapi}...) to the "name version" of a product, things get really hairy. People don't want to deal with product names like "OS MCCXI (1211.1.2)" or "Chrome 43094321".

The disconnect comes from the fact that humans use version numbers to represent fundamental product changes to end users. This is completely decoupled from the API, actually. The old API might still be resepected, even after a logical change to the product version.

So, <vanity>. can give you a way to represent a logical increment on the whole product line.

Also, for big projects, reaching 1.0 should mean something. And you should be able to give people APIs with proper <semver> assurances before you have your 1.0 "ok you can trust me now" launch (right node?). And, at the same time, I don't buy this "oh just label it 0. at the beginning". If I'm consuming your code -- even alpha! -- i want to know when it has broken. Follow semver from the start. npm agrees and has been initing modules at 1.0.0 for a while now..

jbenet commented 8 years ago

Mention (sarcastically :) ) by substack here: https://twitter.com/substack/status/603916951535095808

but i do think it provides meaning to humans.

daviddias commented 8 years ago

vanity could even be a codename or simply a name that is not a version number, making it easier to identify collections of versions, or eras of the software, making it easier for non IT to get a clear picture of the differences in the feature set of each 'era' of the software.

Patching what we have right now is the hard part, I guess. More problematic even is that with having everything broken down into tiny modules, having a common vanity for all might be weird, no? One way could be to add the 'vanity' to the tagged release/binary produced.

jbenet commented 8 years ago

Patching what we have right now is the hard part

@diasdavid yeah, i wouldn't expect npm to change. but other things in the future might first, and if it turns out to be good can be added later

One way could be to add the 'vanity' to the tagged release/binary produced.

Yeah, that sounds good.

bcomnes commented 8 years ago

How does semver work in go? Git tags? Maybe if its less dependent on an existing package manager, there would be room to experiment.

I thing the 4th version number makes sense, especially when projects have multiple support/stability tracks e.g. ESR node.js and Cutting edge io.js.

jbenet commented 8 years ago

How does semver work in go? Git tags? Maybe if its less dependent on an existing package manager, there would be room to experiment.

it doesn't. few if any use it.

I thing the 4th version number makes sense, especially when projects have multiple support/stability tracks e.g. ESR node.js and Cutting edge io.js.

yeah

ema-fox commented 8 years ago

Is my assumption correct that when <vanity> gets incremented that the semvar part gets reset to zeros?

bcomnes commented 8 years ago

Thinking more on this. Is it a really a good idea to mix semver and vanity? Semver isn't just an interface change indicator. It's used to calculate which package to install (at least in node). Its already easy to break that calculation (http://semver.npmjs.com/ e.g. start with 0.0.1) Maybe it would be better to have a totally separate vanity version, and increment that however you want, whist maintaining semver as is. Could there be some kind of ascii char or symbol that could be used to indicate the difference?

ema-fox commented 8 years ago

@bcomnes for me the attraction of having a vanity version number is to reduce cognitive load. Having to maintain a mapping (In people's head and on "paper") between vanity versions and semantic versions seems counter productive.

jbenet commented 8 years ago

some additional notes from https://github.com/electron/electron/issues/5561#issuecomment-219679765

Re: "version numbers like v32.15.0", i understand and agree with the problem of saying "Electron v32" (we have it in the Go and multi-language communities). Consider this or something similar:

"vanity semver": <vanity>.<major>.<minor>.<patch>, where <vanity> is for marketing and the rest is for API changes.

Eg. 1.32.15.0 or really, "Electron v1" with package-manager friendly semver 32.15.0.

Some very relevant notes here, but i do not mean to derail. vanity semver discussion can happen here, or another thread (many, many people have suggested this kind of a thing. there's some other threads likely).

dominictarr commented 8 years ago

things end up at high major version numbers (90.0.1!) pretty quickly.

Please point to a real instance where this actually happens. I've written literally hundreds of modules, and the highest I have gotten to is 15. And I've searched through the npm registry, at least, and I have failed to find modules that have high major semver numbers and have actually stepped through each number sequentially, higher than say 15.

What my experience has been, is that apis tend to coalesce and so probably you figure out what you are building, and then stop changing, OR, you realize you where building a totally different thing and start over with a new name and a new version number. I don't see any actual evidence that you would end up at 90 or 42 or whatever, although I do frequently see people making arguments that you would.

Not that this point undermines the idea of vanity semver. vanity-semver is fully sentimental-versioning compliant.

jbenet commented 8 years ago

@dominictarr

Please point to a real instance where this actually happens.

That's Version 51.0.2704.84.

This is not just for node. It's to expand semver into products.

Instead of generalizing from what you do, maybe consider the constraints different people and ecosystems have.

Not that this point undermines the idea of vanity semver. vanity-semver is fully sentimental-versioning compliant.

Oh wow! Of course, now I see: every experiment in versioning -- except the Almighty Semantic Versioning -- is just an exercise in sentimentalism! No versioning scheme -- except the Almighty -- has ever or could ever help communities find robust dependability, logical meaning, or any utility, really. I'm so glad you made that page! It has enlightened me; i now see the error in the ways of ... everybody except the Semver Inquisition! After all, absolutely zero others are building dependable, robust, logical, well versioned modules, and cannot possibly have anything to contribute. Let's mock everyone who doesn't think like us! \o/

(for other observers, @dominictarr and I are good friends and know each other pretty well, so I feel fine illustrating the problematic dickishness i saw in his (otherwise hilarious) page with equivalent dickishness)

dominictarr commented 8 years ago

Friends with sometimes very differing opinions.

Sorry, I didn't mean to say vanity semver is nonsense, or not worth using. it's a completely reasonable idea for products that have a marketing aspect.

But, to argue the other point...

I think chrome is a bit of a stretch there, that 51 isn't a major change in the semver sense, pretty sure they didn't remove anything.... from https://www.chromium.org/developers/version-numbers

MAJOR and MINOR may get updated with any significant Google Chrome release (Beta or Stable update). MAJOR must get updated for any backwards incompatible user data change (since this data survives updates). BUILD must get updated whenever a release candidate is built from the current trunk (at least weekly for Dev channel release candidates). The BUILD number is an ever-increasing number representing a point in time of the Chromium trunk. PATCH must get updated whenever a release candidate is built from the BUILD branch.

That isn't semver... MAJOR doesn't mean breaking change (you can't move forward) it means you can't downgrade. That is how semver minor works. so chrome doesn't use a major in the semver sense at all.

i'm not an orthodox semverist. there are lots of problems with semver (spec is way too big, mainly) ultimately, any version number scheme so far devised still has a siginificant element of judgement. If it was just an objective calculation we would have so many arguments about it

dominictarr commented 8 years ago

sorry, I thought about this twice after posting, and realized that no, they are actually removing things, tiny things, and thus utilizing a semverlike pretty correctly.

cdepillabout commented 2 years ago

What's described here as Vanity Semver has been long-used by the Haskell community, where it is called the "Haskell Package Versioning Policy (PVP)": https://pvp.haskell.org/. It pre-dates Semver.

If you Google for haskell pvp vs semver, you get some interesting discussion threads for the pros and cons of each: https://www.google.com/search?q=haskell+pvp+vs+semver